Polish translation agent skill

Author: eos87

.github/skills/translate-po/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: translate-po
-description: Use this when asked to update a PO translation catalog with GitHub Copilot. It refreshes the POT file, syncs the target PO file, fills safe untranslated entries, validates the result, and prepares a pull request.
+description: Use this when asked to update a PO translation catalog with GitHub Copilot. It uses the POT file already prepared on the branch, syncs the target PO file, fills safe untranslated entries, validates the result, and prepares a pull request.
 ---
 
 # Translate PO catalogs
@@ -15,40 +15,66 @@ Use this skill when asked to update translations in `superdesk-client-core`.
 - Optional glossary file, for example `docs/i18n/es-glossary.md`
 - Translation rules: `docs/i18n/translation-rules.md`
 
-## Required workflow
+## Environment requirements
+
+Before doing any translation work, ensure the environment is ready:
 
-1. Refresh the source template:
+1. Use Node.js 22.
+2. Install project dependencies:
 
 ```bash
-npm run gettext-extract
+npm ci
 ```
 
-2. Sync the PO file structurally from the template:
+3. Ensure GNU gettext tools are installed and available on PATH:
+   - `msgmerge`
+
+## POT preconditions
+
+Assume `po/superdesk.pot` was prepared by a human developer in a complete local environment.
+
+- Do not run `npm run gettext-extract` as part of the agent workflow.
+- Use the existing `po/superdesk.pot` already present on the branch as the source of truth.
+- If the POT on the branch looks incomplete or inconsistent, stop and explain the problem instead of regenerating it.
+
+## Required workflow
+
+1. Sync the PO file structurally from the template already present on the branch:
 
 ```bash
 npm run gettext-update-po -- <lang>
 ```
 
-3. Fill only empty `msgstr` and `msgstr[n]` entries in `po/<lang>.po`.
+2. Fill only empty `msgstr` and `msgstr[n]` entries in `po/<lang>.po`.
 
-4. Validate the result:
+3. Validate the result:
 
 ```bash
 grunt nggettext_compile
 ```
 
-5. Prepare a pull request against `develop`.
+4. Prepare a pull request against `develop`.
+
+## Sync safety checks
+
+After syncing `po/<lang>.po` from the POT:
+
+- check that existing translations were not removed unexpectedly
+- if a large number of entries suddenly become obsolete, stop and investigate before translating
+- treat mass obsolescence of planning or analytics entries as a failure signal, not as a valid update
 
 ## Hard rules
 
 - Never modify runtime JSON files directly.
 - Never edit `msgid`.
 - Never rewrite unrelated entries.
 - Never overwrite existing non-empty translations.
+- Do not prune obsolete entries during agent-driven PO sync.
 - Preserve all `{{...}}` placeholders exactly, including spacing and nested expressions.
 - Preserve plural structures exactly.
 - Keep diffs minimal and reviewable.
 - Follow the target-language glossary when one exists.
+- Clean up unnecessary whitespace in translated strings before saving.
 
 ## Skip rules
 
@@ -59,6 +85,15 @@ Skip the entry and leave it unchanged if it is:
 - unsafe because of unusual placeholders or formatting
 - likely to require broader terminology review
 
+## Whitespace and punctuation rules
+
+- Do not introduce leading or trailing spaces in translated text.
+- Do not introduce double spaces unless they are already required by the source.
+- Do not add spaces before punctuation marks in Spanish.
+- Do not add unnecessary spaces inside parentheses, quotes, or around slashes.
+- Preserve placeholder text exactly, but make the surrounding Spanish punctuation and spacing natural.
+- Before saving, re-read each changed entry once focusing only on whitespace and punctuation.
+
 ## Current Spanish configuration
 
 For the current Spanish workflow:

docs/i18n/ai-agent-instructions.md

@@ -10,12 +10,32 @@ Follow these rules when updating translations in `superdesk-client-core`.
 - Optional excluded PO files: any locale-specific files that the workflow marks as out of scope
 - Optional glossary: a language-specific glossary file if one exists
 
+## Environment Requirements
+
+- Use Node.js 22.
+- Install project dependencies with `npm ci`.
+- Ensure GNU gettext tools are installed and available:
+  - `msgmerge`
+
+## POT Preconditions
+
+Assume `po/superdesk.pot` was prepared outside the agent flow.
+
+- Do not run `npm run gettext-extract` as part of the agent flow.
+- Use the existing `po/superdesk.pot` already present on the branch as the source of truth.
+- If the POT on the branch looks incomplete or inconsistent, stop and explain the problem instead of regenerating it.
+
 ## Required Workflow
 
-1. Assume `npm run gettext-extract` has refreshed `po/superdesk.pot`.
+1. Use the existing `po/superdesk.pot` on the branch as the source of truth.
 2. Assume `npm run gettext-update-po -- <lang>` has structurally synced `po/<lang>.po`.
 3. Only then fill missing translations in `po/<lang>.po`.
 
+## Sync Safety Checks
+
+- After PO sync, verify that existing translations were not removed unexpectedly.
+- If many entries suddenly become obsolete, especially in planning or analytics areas, treat it as an extraction-environment problem and stop.
+
 ## Hard Rules
 
 - Never modify runtime JSON files directly.
@@ -24,10 +44,12 @@ Follow these rules when updating translations in `superdesk-client-core`.
 - Never touch excluded locale files.
 - Never overwrite existing non-empty translations.
 - Only fill empty `msgstr` or empty plural `msgstr[n]` values when safe.
+- Do not prune obsolete entries during agent-driven PO sync.
 - Preserve all `{{...}}` placeholders exactly, including spacing and nested expressions.
 - Preserve plural structures exactly.
 - Keep diffs minimal and reviewable.
 - Follow the glossary for the target language if one is provided.
+- Remove unnecessary whitespace before saving translated strings.
 
 ## Skip Rules
 
@@ -38,6 +60,15 @@ Skip the entry and leave it unchanged if it is:
 - unsafe because of unusual placeholders or formatting
 - likely to require broader terminology review
 
+## Whitespace Rules
+
+- Do not add leading or trailing spaces.
+- Do not add double spaces unless the source requires them.
+- Do not add spaces before punctuation marks.
+- Do not add unnecessary spaces inside parentheses, quotes, or around slashes.
+- Preserve placeholders exactly, but keep surrounding Spanish spacing natural.
+- Re-read changed translations once with a whitespace-only review before finishing.
+
 ## Validation Mindset
 
 - Existing compile and validation tooling is the final safety net.

docs/i18n/translation-rules.md

@@ -6,6 +6,7 @@ This document defines the current rules for AI-assisted Spanish localization in
 
 - Source of truth for new and changed strings is `po/superdesk.pot`.
 - Initial write target is `po/es.po` only.
+- `po/superdesk.pot` should be refreshed by a human developer before the agent translation step.
 - Do not modify runtime JSON files directly.
 - Run `npm run gettext-update-po -- es` before asking AI to translate.
 - Do not change extraction, compile, or validation tooling.
@@ -15,7 +16,8 @@ This document defines the current rules for AI-assisted Spanish localization in
 
 - Translate only entries that exist in `po/superdesk.pot`.
 - Update only matching entries in `po/es.po`.
-- Let the sync step add or remove catalog entries structurally.
+- Let the sync step add matching catalog entries structurally.
+- Do not prune obsolete entries as part of the agent-driven update flow.
 - Never modify `msgid`.
 - Never rewrite unrelated entries.
 - Do not overwrite existing non-empty Spanish translations.
@@ -49,15 +51,14 @@ When skipping, leave the entry unchanged.
 
 After preparing changes:
 
-1. Refresh the template with `npm run gettext-extract`.
+1. Ensure `po/superdesk.pot` was refreshed by a human developer in a known complete environment.
 2. Sync the Spanish catalog with `npm run gettext-update-po -- es`.
 3. Ensure AI changes are limited to translation content in `po/es.po`.
 4. Ensure `msgid` values are untouched.
 5. Ensure placeholders and plural structures still match the source exactly.
 6. Run the existing compile/validation flow so current tooling can reject invalid placeholder changes:
 
 ```bash
-npm run gettext-extract
 npm run gettext-update-po -- es
 grunt nggettext_compile
 ```

docs/i18n/translation-workflow.md

@@ -4,37 +4,36 @@ This is the manual GitHub Copilot agent workflow for AI-assisted translations in
 
 ## Flow
 
-1. Ask the GitHub Copilot agent to update Spanish translations using the repository skill in `.github/skills/translate-po/`.
+1. A human developer refreshes `po/superdesk.pot` in a known complete local environment before invoking the agent.
 
-2. The agent refreshes the source template:
+2. Ask the GitHub Copilot agent to update translations for the target language using the repository skill in `.github/skills/translate-po/`.
 
-```bash
-npm run gettext-extract
-```
+3. The agent uses the existing `po/superdesk.pot` on the branch as the source of truth.
 
-3. The agent syncs the target PO file from the template:
+4. The agent syncs the target PO file from the template:
 
 ```bash
 npm run gettext-update-po -- es
 ```
 
-4. The agent fills empty `msgstr` and `msgstr[n]` entries in `po/es.po`, using `po/superdesk.pot` as the source of truth.
+5. The agent fills empty `msgstr` and `msgstr[n]` entries in `po/es.po`, using `po/superdesk.pot` as the source of truth.
 
-5. The agent validates with existing tooling:
+6. The agent validates with existing tooling:
 
 ```bash
 grunt nggettext_compile
 ```
 
-6. The agent prepares a PR against `develop`.
+7. The agent prepares a PR against `develop`.
 
-7. Review the diff and the PR.
+8. Review the diff and the PR.
 
 ## AI Step Boundaries
 
 - Read `po/superdesk.pot` as the source of truth.
 - Update only `po/es.po`.
 - Translate only empty entries in `po/es.po`.
+- Do not prune obsolete entries during the agent-driven sync step.
 - Never modify runtime JSON files directly.
 - Never edit `msgid`.
 - Never overwrite non-empty Spanish translations.
@@ -44,7 +43,8 @@ grunt nggettext_compile
 ## Notes
 
 - `npm run gettext-update-po -- <lang>` is generic and can be reused for other existing top-level PO files later.
-- The current workflow remains Spanish-only for AI translation.
+- The current examples use Spanish (`es`), but the agent workflow and skill are designed to work for other supported languages too.
 - The primary trigger is manual: ask the GitHub Copilot agent to perform the translation update.
+- `npm run gettext-extract` is intentionally outside the agent flow and should be run by a human developer when the POT needs to be refreshed.
 - The repository skill for this lives in `.github/skills/translate-po/SKILL.md`.
 - `docs/i18n/ai-agent-instructions.md` contains the generic agent rules; this document defines the current Spanish run configuration.

tasks/gettext-update-po.js

@@ -42,21 +42,9 @@ try {
         ],
         {stdio: 'inherit'}
     );
-
-    execFileSync(
-        'msgattrib',
-        [
-            '--no-obsolete',
-            '--no-wrap',
-            '-o',
-            poFile,
-            poFile,
-        ],
-        {stdio: 'inherit'}
-    );
 } catch (error) {
     if (error.code === 'ENOENT') {
-        console.error('GNU gettext tools are required. Ensure "msgmerge" and "msgattrib" are installed.');
+        console.error('GNU gettext tools are required. Ensure "msgmerge" is installed.');
     }
 
     process.exit(error.status ?? 1);