feat(i18n): fill 725 empty Spanish translations in po/es.po [POC - ignore for now]

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

@@ -0,0 +1,71 @@
+---
+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.
+---
+
+# Translate PO catalogs
+
+Use this skill when asked to update translations in `superdesk-client-core`.
+
+## Inputs
+
+- Target language code, for example `es`
+- Target PO file, for example `po/es.po`
+- Source of truth: `po/superdesk.pot`
+- Optional glossary file, for example `docs/i18n/es-glossary.md`
+- Translation rules: `docs/i18n/translation-rules.md`
+
+## Required workflow
+
+1. Refresh the source template:
+
+```bash
+npm run gettext-extract
+```
+
+2. Sync the PO file structurally from the template:
+
+```bash
+npm run gettext-update-po -- <lang>
+```
+
+3. Fill only empty `msgstr` and `msgstr[n]` entries in `po/<lang>.po`.
+
+4. Validate the result:
+
+```bash
+grunt nggettext_compile
+```
+
+5. Prepare a pull request against `develop`.
+
+## Hard rules
+
+- Never modify runtime JSON files directly.
+- Never edit `msgid`.
+- Never rewrite unrelated entries.
+- Never overwrite existing non-empty translations.
+- 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.
+
+## Skip rules
+
+Skip the entry and leave it unchanged if it is:
+
+- HTML-heavy
+- ambiguous without UI or product context
+- unsafe because of unusual placeholders or formatting
+- likely to require broader terminology review
+
+## Current Spanish configuration
+
+For the current Spanish workflow:
+
+- target language: `es`
+- target file: `po/es.po`
+- glossary: `docs/i18n/es-glossary.md`
+- rules: `docs/i18n/translation-rules.md`
+
+When asked to update Spanish translations, use this skill together with the Spanish glossary and rules.

docs/i18n/ai-agent-instructions.md

@@ -0,0 +1,44 @@
+# AI Agent Instructions For PO Updates
+
+Follow these rules when updating translations in `superdesk-client-core`.
+
+## Inputs
+
+- Source of truth: `po/superdesk.pot`
+- Target language code: `<lang>`
+- Target PO file: `po/<lang>.po`
+- 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
+
+## Required Workflow
+
+1. Assume `npm run gettext-extract` has refreshed `po/superdesk.pot`.
+2. Assume `npm run gettext-update-po -- <lang>` has structurally synced `po/<lang>.po`.
+3. Only then fill missing translations in `po/<lang>.po`.
+
+## Hard Rules
+
+- Never modify runtime JSON files directly.
+- Never edit `msgid`.
+- Never rewrite unrelated entries.
+- Never touch excluded locale files.
+- Never overwrite existing non-empty translations.
+- Only fill empty `msgstr` or empty plural `msgstr[n]` values when safe.
+- 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.
+
+## Skip Rules
+
+Skip the entry and leave it unchanged if it is:
+
+- HTML-heavy
+- ambiguous without UI or product context
+- unsafe because of unusual placeholders or formatting
+- likely to require broader terminology review
+
+## Validation Mindset
+
+- Existing compile and validation tooling is the final safety net.
+- If a translation would require changing placeholders, plural structure, or source identifiers, do not make the change.

docs/i18n/es-glossary.md

@@ -0,0 +1,47 @@
+# Spanish Glossary
+
+Use neutral product Spanish. Prefer consistency over stylistic variation.
+
+## Core Terms
+
+- article -> artículo
+- item -> elemento
+- content -> contenido
+- headline -> titular
+- slugline -> slugline
+- byline -> firma
+- desk -> mesa
+- stage -> etapa
+- workspace -> espacio de trabajo
+- assignment -> asignación
+- planning -> planificación
+- event -> evento
+- coverage -> cobertura
+- vocabulary -> vocabulario
+- dictionary -> diccionario
+- template -> plantilla
+- preview -> vista previa
+- publish -> publicar
+- unpublish -> retirar de publicación
+- schedule -> programar
+- save -> guardar
+- close -> cerrar
+- filter -> filtro
+- search -> buscar
+- settings -> configuración
+- user -> usuario
+- language -> idioma
+- translation -> traducción
+
+## Tone
+
+- Keep labels short and UI-friendly.
+- Prefer imperative verbs for actions, for example `Guardar`, `Cerrar`, `Publicar`.
+- Prefer neutral Spanish over regional wording.
+- Keep product names such as `Superdesk` untranslated.
+
+## Consistency Rules
+
+- Preserve established translations already present in `po/es.po` unless they are clearly wrong and separately approved for correction.
+- Do not translate placeholders, field identifiers, or internal codes.
+- If a source term is ambiguous, leave it for manual review instead of forcing a glossary match.

docs/i18n/translation-rules.md

@@ -0,0 +1,78 @@
+# AI-Assisted Spanish Translation Rules
+
+This document defines the current rules for AI-assisted Spanish localization in `superdesk-client-core`.
+
+## 1. Scope
+
+- Source of truth for new and changed strings is `po/superdesk.pot`.
+- Initial write target is `po/es.po` only.
+- 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.
+- Existing compile and validation steps remain the final safety net.
+
+## 2. Translation Rules
+
+- 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.
+- Never modify `msgid`.
+- Never rewrite unrelated entries.
+- Do not overwrite existing non-empty Spanish translations.
+- Only fill empty Spanish translations that are safe and clear.
+- Keep wording neutral Spanish unless the source clearly requires a specific term.
+- Keep diffs minimal and easy to review.
+
+## 3. Placeholder Preservation Rules
+
+- Preserve all `{{...}}` placeholders exactly as they appear in the source.
+- Preserve placeholder spacing exactly, including forms like `{{name}}`, `{{ name }}`, `{{ $count}}`, and nested expressions such as `{{user.full_name}}`.
+- Do not translate, rename, reorder, add, or remove placeholders.
+- Preserve plural structures exactly: `msgid`, `msgid_plural`, and every `msgstr[n]` slot required by the target entry.
+- Never collapse plural entries into singular entries or vice versa.
+- Preserve inline markup and escaped characters exactly when translating around them.
+
+## 4. Skip Conditions
+
+Skip an entry if any of the following is true:
+
+- The entry already has a non-empty `msgstr` or plural `msgstr[n]`.
+- The entry is HTML-heavy or contains markup that makes safe translation unclear.
+- The meaning is ambiguous without product or UI context.
+- The entry contains unsafe or unclear placeholder usage.
+- The entry has unusual formatting, broken source text, or translator notes suggesting manual review is safer.
+- The entry would require changing anything outside the exact target message block.
+
+When skipping, leave the entry unchanged.
+
+## 5. Validation Steps
+
+After preparing changes:
+
+1. Refresh the template with `npm run gettext-extract`.
+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
+```
+
+If a broader build check is needed, use the normal project build flow instead of editing generated JSON by hand.
+
+## 6. Definition Of Done
+
+The translation step is done when:
+
+- `po/superdesk.pot` has been refreshed from source.
+- `po/es.po` has been structurally synced from the POT via `npm run gettext-update-po -- es`.
+- Only safe, empty Spanish entries in `po/es.po` were filled by the AI step.
+- Runtime JSON files were not modified.
+- No existing non-empty Spanish translations were overwritten.
+- All placeholders, plural forms, and source identifiers were preserved exactly.
+- The diff is small, targeted, and reviewable.
+- Existing compile/validation tooling passes or remains the final blocker for anything invalid.

docs/i18n/translation-workflow.md

@@ -0,0 +1,50 @@
+# AI Translation Workflow
+
+This is the manual GitHub Copilot agent workflow for AI-assisted translations in `superdesk-client-core`.
+
+## Flow
+
+1. Ask the GitHub Copilot agent to update Spanish translations using the repository skill in `.github/skills/translate-po/`.
+
+2. The agent refreshes the source template:
+
+```bash
+npm run gettext-extract
+```
+
+3. 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 validates with existing tooling:
+
+```bash
+grunt nggettext_compile
+```
+
+6. The agent prepares a PR against `develop`.
+
+7. 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`.
+- Never modify runtime JSON files directly.
+- Never edit `msgid`.
+- Never overwrite non-empty Spanish translations.
+- Preserve placeholders and plural blocks exactly.
+- Skip HTML-heavy, ambiguous, or unsafe entries.
+
+## 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 primary trigger is manual: ask the GitHub Copilot agent to perform the translation update.
+- 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.

package.json

@@ -165,6 +165,7 @@
   },
   "scripts": {
     "gettext-extract": "grunt gettext:extract",
+    "gettext-update-po": "node ./tasks/gettext-update-po.js",
     "postinstall": "node ./tasks/patch-package.js && node tasks/generate-placeholder-file-for-extension-styles.js",
     "test": "npm run lint && npm run unit && npm run verify-client-api-changes",
     "debug-unit-tests": "karma start --reporters=progress --browsers=Chrome",