ContextQMD
Back to Unigetui

translation diff import

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

2026.1.92.7 KB
Original Source

translation diff import

Use this skill after the export skill produced a .source.json, .translated.json, and .reference.json set and you want to merge the translated working copy back into the full target-language JSON file.

See translation-diff-export for the patch-generation step that produces the expected inputs.

Prerequisites

  • PowerShell 7 (pwsh).
  • cirup available on PATH.

Scripts

  • scripts/import-translation-diff.ps1: Validates and merges a translated patch into the full language file.
  • scripts/validate-language-file.ps1: Validates placeholder, token, HTML-fragment, and newline parity for either a full language file or just the active patch keys against lang_en.json.

Usage

Import the translated French working copy from the export skill into the full French JSON file:

powershell
pwsh ./.agents/skills/translation-diff-import/scripts/import-translation-diff.ps1 \
  -TranslatedPatch ./generated/translation-diff-export/lang.diff.fr.translated.json \
  -SourcePatch ./generated/translation-diff-export/lang.diff.fr.source.json \
  -TargetJson ./src/Languages/lang_fr.json \
  -NeutralJson ./src/Languages/lang_en.json \
  -OutputJson ./src/Languages/lang_fr.merged.json

Validate the merged output:

powershell
pwsh ./.agents/skills/translation-diff-import/scripts/validate-language-file.ps1 \
  -NeutralJson ./src/Languages/lang_en.json \
  -TargetJson ./src/Languages/lang_fr.merged.json \
  -PatchJson ./generated/translation-diff-export/lang.diff.fr.source.json

Optional parameters:

  • -OutputDir (default: generated/translation-diff-import)
  • -AllowUnchangedValues
  • -KeepIntermediate

Recommended input mapping from the export skill:

  • -TranslatedPatch: generated/translation-diff-export/lang.diff.fr.translated.json
  • -SourcePatch: generated/translation-diff-export/lang.diff.fr.source.json

Output

  • A merged .json file that contains both the previously translated entries and the imported patch values.
  • If -KeepIntermediate is used, patch snapshots are preserved under generated/translation-diff-import/tmp/.

Edge cases

  • If the target JSON file does not exist yet, the script can create an output from the translated patch alone.
  • When -SourcePatch is provided, the script validates translated keys, placeholder tokens, HTML-like fragments, newline counts, and likely untranslated values before delegating the merge to cirup while allowing missing keys for partial progress.
  • The import skill expects .translated.json to remain sparse. Untranslated keys should be omitted instead of copied in English unless you intentionally bypass that check with -AllowUnchangedValues.