Translation Source Sync

translation source sync

Use this skill when UniGetUI source code changed and you need to keep src/Languages/lang_en.json aligned with the strings actually used by the application, or when you need downstream locale files reordered to match the English key ordering.

It scans supported C#, WinUI XAML, and Avalonia AXAML patterns, finds missing English keys, removes unused entries, reports translation-source warnings that still need manual cleanup, and can align locale file ordering to the English layout.

Scope

• Extract literal translation keys from supported UniGetUI source patterns.
• Add new English keys missing from lang_en.json.
• Remove English keys that are no longer used.
• Reorder non-English locale files to match the English key ordering.
• Warn about interpolated CoreTools.Translate($"...") calls that are not synchronized automatically.
• Leave downstream language propagation to the existing translation diff workflow.

Supported extraction sources

• CoreTools.Translate("...") in C#.
• CoreTools.AutoTranslated("...") in C#.
• widgets:TranslatedTextBlock Text="..." in WinUI XAML.
• settings:TranslatedTextBlock Text="..." in Avalonia AXAML.
• {t:Translate Some text} and {t:Translate Text='A, B, C'} in Avalonia AXAML.

Out of scope for v1

• Interpolated translation calls such as CoreTools.Translate($"Running {value}").
• Non-literal translation inputs passed through variables.
• CI enforcement.

Scripts

• scripts/sync-translation-sources.ps1: Skill wrapper around the repository sync script.
• scripts/set-translation-boundary-order.ps1: Skill wrapper around the repository locale reordering script.
• scripts/test-translation-source-sync.ps1: Skill wrapper around the repository smoke test.
• ../../../../scripts/translation/Sync-TranslationSources.ps1: Canonical repository implementation used by the wrapper.
• ../../../../scripts/translation/Set-TranslationBoundaryOrder.ps1: Canonical repository implementation used by the wrapper.
• ../../../../scripts/translation/Test-TranslationSourceSync.ps1: Canonical smoke test used by the wrapper.

Usage

Synchronize the checked-in English language file in place:

pwsh ./.agents/skills/translation-source-sync/scripts/sync-translation-sources.ps1

Check whether the English file is out of sync without writing changes:

pwsh ./.agents/skills/translation-source-sync/scripts/sync-translation-sources.ps1 -CheckOnly

Reorder locale files to match the English key ordering:

pwsh ./.agents/skills/translation-source-sync/scripts/set-translation-boundary-order.ps1

Preview whether locale files need reordering without writing changes:

pwsh ./.agents/skills/translation-source-sync/scripts/set-translation-boundary-order.ps1 -CheckOnly

Run the smoke test:

pwsh ./.agents/skills/translation-source-sync/scripts/test-translation-source-sync.ps1

Recommended workflow

1. Run translation source sync after changing any translatable source string.
2. If -CheckOnly reports drift, run the full sync to rewrite lang_en.json.
3. Review warnings for interpolated translation calls and convert them to stable literals or add the missing English keys manually when needed.
4. Run pwsh ./.agents/skills/translation-source-sync/scripts/set-translation-boundary-order.ps1 to align locale ordering with English.
5. Run pwsh ./scripts/translation/Verify-Translations.ps1 to confirm the language files still validate cleanly.
6. Run pwsh ./.agents/skills/translation-source-sync/scripts/test-translation-source-sync.ps1 if you changed the sync workflow itself.
7. Export changed work for translators with translation-diff-export.

Notes

• Existing English values are preserved for retained keys; newly added English entries default to key == value.
• The sync script preserves current key order for retained entries and appends newly discovered keys deterministically.
• The locale reorder script follows English as the canonical order and appends unmapped locale-only keys at the end.
• The smoke test uses a temporary synthetic repo so it does not mutate the checked-in language files.