Localize AI Project

Localize AI Project

Overview

Use this skill to localize AI/open-source applications into Ukrainian end to end: discover the i18n system, translate or polish locale files, validate placeholders and formatting, test the UI when possible, then publish a GitHub PR.

For optional model-assisted translation setup, read references/translation-providers.md only when the user provides or asks to use a local/remote LLM provider.

Workflow

1. Resolve the target repository, fork/branch permissions, and requested scope.
2. Inspect the project before editing:
   • identify framework, package manager, source locale, target locale naming (uk or uk-UA), and i18n file formats;
   • check whether Ukrainian already exists and whether this is add-new-locale or polish-existing-locale work;
   • list relevant commands for parsing, linting, tests, and local app startup.
3. Define success criteria:
   • source locale keys are represented in Ukrainian;
   • placeholders, tags, markdown, HTML, ICU/plural syntax, and escape sequences are preserved;
   • parse/format/lint/i18n checks pass;
   • if feasible, the UI can switch to Ukrainian and key screens render without broken text.
4. Create or switch to a focused branch, usually i18n/add-ukrainian-locale or i18n/update-ukrainian-locale.
5. Translate manually or in batches with a user-provided LLM provider, then edit for natural Ukrainian. If no provider is configured, proceed without model-assisted translation.
6. Keep changes surgical. Do not refactor unrelated code, rename unrelated keys, or add speculative i18n infrastructure unless the project requires it for Ukrainian support.
7. Validate locally and fix issues.
8. Commit, push, open/update the PR, inspect GitHub checks and review comments, and address actionable feedback.

Translation Rules

• Use natural Ukrainian UI language, not literal machine calques.
• Keep technical identifiers intact when translating them would change meaning: API, CLI, model names, env vars, file paths, command names, package names, and code symbols.
• Preserve placeholders exactly, including forms like {name}, {{count}}, %s, $1, <0>...</0>, ICU variables, and interpolation braces.
• Preserve markdown, HTML tags, links, keyboard shortcuts, line breaks that are semantically intentional, and escape sequences.
• Respect Ukrainian pluralization. Do not copy English plural assumptions when the i18n library supports language-specific plural forms.
• Maintain a short glossary for recurring terms. Prefer consistent translations across the project.
• Scan for mojibake, split words, duplicated syllables, mixed-script artifacts, and awkward hybrids such as deselect-ться.

Model-Assisted Translation

Use model assistance only when the user explicitly provides a provider or asks to configure one. Read references/translation-providers.md for supported patterns.

Use model output as draft material, not as final text. Always do a native Ukrainian editorial pass, especially for settings/tooltips, action labels, security text, and user-facing errors.

Never require Gemma, llama.cpp, MiMo, OpenAI, Ollama, or any other provider. If no provider is available, translate and review directly. Never print, commit, or write API keys; read secrets from environment variables only.

Validation Checklist

• Parse all changed JSON/YAML/TS locale files with structured tooling.
• Compare source and Ukrainian key sets.
• Compare placeholder sets between source strings and translations.
• Run project format/lint/i18n/unit checks when available.
• For web UI projects, start the app when feasible and verify Ukrainian in the browser on representative screens.
• After pushing, inspect PR checks, comments, review threads, and CLA status. Do not sign CLA or any legal agreement for the user; report exact required user action.

GitHub Output

End with:

• PR link and commit hash;
• changed files;
• translation provider used, or state that translation was done without model assistance;
• checks run and their results;
• remaining blockers or user-only actions.