Overhaul translation tooling and freeze bundled language assets

.agents/skills/translation-diff-export/SKILL.md

@@ -1,31 +1,29 @@
 ---
 name: translation-diff-export
-description: Export a JSON translation patch containing only untranslated or source-changed UniGetUI strings for a target language.
+description: Compares UniGetUI JSON locale files against English, identifies untranslated or source-changed keys, and generates patch, reference, and handoff files for a target language. Use when the user asks to export missing translations, untranslated strings, i18n diffs, or locale-file changes.
 ---
 
 # translation diff export
 
 Use this skill when you need a small UniGetUI translation patch instead of sending a full language JSON file for review or translation.
 
-## Scope
-
-- Export only strings that are still untranslated in the target language file.
-- Treat missing, empty, or English-equal target values as untranslated.
-- Optionally include strings whose English source value changed since a git baseline.
-- Produce an immutable English source patch, a sparse translated working copy, and a translated reference corpus.
-- Generate a companion markdown handoff file that points the translator to `translation-diff-translate` and the merge step in `translation-diff-import`.
+It exports only the active untranslated or source-changed strings, creates the translator handoff files, and prepares the patch set needed by `translation-diff-translate` and `translation-diff-import`.
 
 ## Prerequisites
 
 - PowerShell 7 (`pwsh`).
 - `git` available on `PATH`.
 - `cirup` available on `PATH`.
 
+When source strings changed, run `translation-source-sync` first so `lang_en.json` reflects current source usage before exporting downstream translation patches.
+
 ## Scripts
 
 - `scripts/export-translation-diff.ps1`: Exports JSON patch artifacts and generates a translation handoff prompt.
 - `scripts/test-translation-diff.ps1`: Runs a local end-to-end smoke test against the checked-in UniGetUI language files.
 
+Use this skill's wrapper scripts first; the downstream translate and import steps are documented in [translation-diff-translate](../translation-diff-translate/SKILL.md) and [translation-diff-import](../translation-diff-import/SKILL.md).
+
 ## Usage
 
 Export untranslated French strings only:
@@ -58,17 +56,6 @@ Run the built-in smoke test:
 pwsh ./.agents/skills/translation-diff-export/scripts/test-translation-diff.ps1
 ```
 
-## How It Works
-
-1. The script loads `lang_en.json` and the selected `lang_{code}.json` file.
-2. It uses `cirup file-diff` to find missing keys and `cirup file-intersect` to find keys whose target value still matches English.
-3. It adds any keys whose target value is present but empty, because those are not surfaced by `cirup` set operations.
-4. If `-BaseRef` is provided, the script loads the old `lang_en.json` from git history and uses `cirup diff-with-base` to include keys that are new or whose English value changed.
-5. It writes the English source patch as JSON.
-6. It writes a reference JSON file containing already translated target-language entries that are outside the current patch.
-7. It creates or refreshes a sparse translated working copy, preserving only still-valid translated entries from a previous patch file.
-8. It invokes `translation-diff-translate` to write a companion `.prompt.md` handoff file for the translation and merge step.
-
 ## Output
 
 For `lang_en.json` and language `fr`, the script generates:
@@ -82,21 +69,22 @@ If `-KeepIntermediate` is used, git-baseline snapshots are kept under `generated
 
 The smoke test writes its temporary artifacts under `generated/translation-diff-export-demo/`.
 
-## Hand Off To Translate
+## Validate The Export
+
+After export, confirm the patch is usable before handing it off:
 
-After exporting the patch, use the generated `.prompt.md` file with `translation-diff-translate` to update the sparse translated working copy.
+1. Check that `.source.json` is not empty unless you expected no work for that language.
+2. Confirm `.translated.json` is sparse and does not contain copied English placeholders for unfinished keys.
+3. If the patch should include recent English changes, rerun with `-BaseRef` and compare the resulting `.source.json`.
+4. Run the smoke test if you changed the export workflow itself.
 
-The generated prompt includes the concrete file paths for:
+## Hand Off To Translate
 
-- `.source.json`
-- `.translated.json`
-- `.reference.json`
-- the full target `lang_{code}.json`
-- the follow-up import and validation commands
+After exporting the patch, use the generated `.prompt.md` file with [translation-diff-translate](../translation-diff-translate/SKILL.md) to update the sparse translated working copy.
 
 ## Hand Off To Import
 
-After translating the patch, merge it back into the full language file:
+After translating the patch, merge it back into the full language file with [translation-diff-import](../translation-diff-import/SKILL.md):
 
 ```powershell
 pwsh ./.agents/skills/translation-diff-import/scripts/import-translation-diff.ps1 \
@@ -107,8 +95,4 @@ pwsh ./.agents/skills/translation-diff-import/scripts/import-translation-diff.ps
   -OutputJson ./src/UniGetUI.Core.LanguageEngine/Assets/Languages/lang_fr.merged.json
 ```
 
-The `.source.json` file stays as the English reference. The `.translated.json` file should contain only completed translations during a partial translation pass.
-
-The `.reference.json` file contains already translated destination-language strings that are not in the current source patch, so the translator can reuse existing terminology and style.
-
 Keep the `.translated.json` file sparse. If a key is not translated yet, leave it out instead of copying the English source value into the working copy.