Translation File Validation: Catch Missing CLDR Plurals in CI
Translation File Validation: Catch Missing CLDR Plurals in CI
Translation file validation checks that translated resource files are both well-formed and consistent with the source: keys, placeholders, plural forms and untranslated values. Automated validators catch what a syntax linter misses. Run them in CI on every pull request, fail the build on parse errors, missing keys and missing CLDR plural categories, and keep a machine-readable report.
TL;DR:
- CLDR requirements vary by language, so English plural structures cannot be copied safely; missing categories can pass a basic parser yet display incorrect count text.
- Treat extra keys and untranslated strings as warnings, because identical values may be valid brand names or labels such as OK.
- Send untranslated copy to translators or localization PMs, placeholder breakage to the translation producer, and stale extra keys to developers.
- Small teams can review only strings changed since the last release, while fluent reviewers assess tone, brand voice, and legal copy that automation cannot judge.
Table of Contents
- What should a translation file validation job check?
- What do validator findings look like in practice?
- Who runs these checks, and who fixes what?
- Why isn’t a basic linter enough for plurals, XLIFF and YAML?
- How do you split manual and automated review?
- How do you add translation file validation to CI?
- What does validated packaging look like at Arkian?
- Our take: start with plurals and a failing build
- Get validated, packaged language files from Arkian
- FAQ
- Sources
What should a translation file validation job check?
A good job runs checks in priority order, so the cheapest and most damaging failures surface first. Each item below catches a specific release problem.
- Syntax and parse errors: invalid JSON, YAML or XML should stop the pipeline immediately. A file that does not parse cannot be loaded, so the build fails or the app silently falls back to the source language.
- Missing and extra keys: compare every target file against a reference language. Missing keys leave gaps in the UI, while orphaned keys point to stale strings that nobody removed.
- Placeholder and interpolation mismatches: detect differing token formats such as
{price},%sand{{name}}, plus differing token counts. A translation that drops{name}ships a sentence with a hole in it. - Plural structure: confirm each translation supplies the plural categories the language requires under CLDR plural rules. Categories such as
one,few,manyandothervary by language, so a copied English structure is often wrong. - Empty and untranslated values: flag empty strings and values identical to the source. Some identical strings are legitimate (brand names, “OK”), so these are review items, not automatic failures.
- Locale code and layout normalization: normalize variants such as
zh-Hansandpt-BR, and verify the folder and file layout matches what your app loader expects.
How should you set severity?
Treat parse errors, missing keys and missing required plural categories as errors that fail the build. Treat extra keys and untranslated strings as warnings. The chki18n CLI follows this pattern, reporting a missing key as an error and an untranslated value as a warning, with structured output for CI.
This split keeps the signal clean. If every warning blocks a merge, developers learn to bypass the check. If real errors only warn, they reach production.
What do validator findings look like in practice?
Concrete snippets make the checks easier to act on. Here is a small English source and a French target with three deliberate problems:
// en.json (reference)
{
"cart.title": "Your cart",
"cart.total": "Total: {price}",
"cart.empty": "Your cart is empty"
}
// fr.json (target)
{
"cart.title": "Votre panier",
"cart.total": "Total : %s",
"cart.legacy": "Ancien texte",
"cart.empty": "Your cart is empty"
}
Reading it against the reference, a validator reports a placeholder mismatch ({price} became %s), an extra key (cart.legacy) and an untranslated value (cart.empty is still English). A CLI line might read: ERROR fr.json cart.total placeholder mismatch: expected {price}, found %s.
| Finding | Example key | Typical severity | Likely owner |
|---|---|---|---|
| Parse error | whole file | Error | Developer |
| Placeholder mismatch | cart.total | Error | Translator or vendor |
| Missing plural category | items.count | Error | Translator |
| Extra key | cart.legacy | Warning | Developer |
| Untranslated value | cart.empty | Warning | Localization PM |
To turn a JSON or JUnit report into work, group findings by file and key, then attach the owner from the table. Include the file path, key, locale, offending snippet and a recommended fix, so nobody has to reproduce the problem to understand it.
Who runs these checks, and who fixes what?
Validation works best when each stage of the pipeline has a named owner. Without one, the same defect gets found three times and fixed zero.
- Localization PMs often trigger validation at handoff, before files go to translators or after they return.
- Vendors should run pre-handoff checks so they do not deliver files with broken placeholders.
- Developers and CI run pre-merge checks on every change to a locale file.
- QA runs a pre-release verification pass against the full set of locales.
Small teams can keep effort low with a recurring lightweight loop that reviews only the strings changed since the last release. That can be a lightweight alternative to a full audit.
Route fixes by finding type. Parse errors go to a developer, untranslated copy goes to the translator or localization PM, and placeholder breakage goes back to whoever produced the translation. If you want worked file-level guidance, our guides on localizing JSON language files and Android XML string files show the layouts these checks assume.
Why isn’t a basic linter enough for plurals, XLIFF and YAML?
A parser only confirms that a file can be read. It does not know that Polish needs more plural forms than English, or that a YAML loader quietly dropped half your keys.
- CLDR plurals: CLDR defines which categories each language needs, and the plural rules chart gives minimal pairs for checking them. Languages differ in their required plural categories, so a missing required form should be an error, not a note.
- XLIFF conformance: an XLIFF 2.2 document must be valid XML and follow the OASIS schema, with required elements and attributes, so different tools process it the same way. Our XLIFF localization workflow guide covers the practical stages for iOS teams.
- YAML pitfalls: the YAML 1.2 specification requires processors to reject ill-formed streams, and duplicate mapping keys, unresolved aliases and unrecognized tags all cause failures. Loader behavior can vary, so use a strict loader. Our YAML localization guide covers the duplicate-key trap.
Plural handling is a language-by-language question: the CLDR plural rules documentation explains that validators need to be CLDR-aware to catch malformed plural structures, because wrong plurals produce broken UI in target markets.
The real danger is the file that parses cleanly and still misbehaves. A string with an incomplete set of plural categories may load without complaint, then show the wrong text for counts that need other categories. Format-aware validation catches that before a user does.
How do you split manual and automated review?
Automate everything that has a right answer, and keep people for everything that needs judgment.
- Automate parse checks, key comparison, placeholder matching and plural requirements. Make the job exit with a nonzero code on any error.
- Reserve human review for tone, brand voice and legal copy. A machine cannot tell whether a phrase sounds friendly or merely correct.
- Triage ambiguous untranslated matches by hand. Identical strings may be product names or genuine misses.
- Set CI severity flags deliberately. Fail on parse errors and missing plural categories, and surface untranslated values and extra keys as warnings.
For teams that automate heavily, the same logic applies upstream: our notes on CI-ready batch translation explain how to keep plurals and placeholders intact before validation even runs. The principle also holds outside software strings. A partner article on automating hreflang in CI/CD makes the same case for regenerating technical output on every change instead of fixing it by hand.
Pro Tip: Run the automated checks on every pull request, then do one short human pass on the changed strings each week.
How do you add translation file validation to CI?
Setup effort varies by project. Follow these steps.
- Pick a validator that auto-detects file layout and emits JSON or JUnit. Tools such as i18n-validate check missing and extra keys, placeholder mismatches, malformed plurals and untranslated strings. PHP projects can use a Composer validator plugin that supports XLIFF, YAML, JSON and PHP formats.
- Add a CI job that runs on the changed locale files or the whole locales folder. Pass the reference language explicitly, for example with a
--ref enflag. - Configure severity per check in a config file. Use a strict flag on protected branches so warnings become failures only where release quality matters most.
- Publish machine-readable output to your CI test report. Link each finding back to the repo, file and key, so a reviewer can jump straight to the fix.
- Fail the pull request on a nonzero exit code. Keep the rule simple enough that nobody has to ask what a red build means.
Run the same job locally before pushing. Developers who see the failure on their own machine fix it in seconds.
What does validated packaging look like at Arkian?
We built validation into packaging so small teams get delivery-ready files without giving us repository access. Our platform produces strings, metadata and voice output, then validates and packages them into reviewable language files, so findings are handled before handoff instead of discovered after it. Proactive validation can help prevent rework and project delays, as a localization engineer notes. You can see the result on a real product in our Quiet Harbour localization case study.
Our take: start with plurals and a failing build
Teams can over-invest in linting syntax and under-invest in plural validation. Syntax errors announce themselves loudly, because the app breaks. Wrong plural forms are quiet. They pass review, pass the parser and surface as awkward text in the languages where your growth is.
So prioritize in this order. First, make parse errors and missing CLDR plural categories fail the build. Second, add placeholder matching, because it can catch placeholder mismatches that may cause runtime issues. Third, treat untranslated strings as a review queue, not a blocker.
Be skeptical of heavy process. A small team does not need a full translation management system to validate files, and a short CI job plus a regular look at changed strings can help catch problems. The benefit comes from running checks every time, not from running sophisticated ones occasionally.
— Arkian
Get validated, packaged language files from Arkian
Prefer not to build and maintain a validator stack yourself? We deliver validated, structured language packages without repository access or a full translation management system. Our localization strings service produces the files, structured packaging organizes them into delivery-ready folders, and we also produce multilingual voice output. Membership is $19.00 CAD per month, and the details are on our pricing page. Check the plans and send your first project through.
FAQ
How do you check if a translation is correct?
Run automated checks first: valid syntax, matching keys, matching placeholders and the required plural forms. Then have a fluent reviewer read the changed strings for meaning and tone, since software cannot judge naturalness.
Is there a way to translate a file?
Yes. You can upload a resource file such as JSON, YAML, Android XML or iOS strings to a translation tool or service and receive a translated file in the same format. Validate the result afterward, because placeholders and plurals can break during translation. See our Localize iOS .strings files page for one format example.
What does translation validity mean?
It usually means a translated file is technically sound and consistent with its source: it parses, keeps every key and placeholder, and supplies the plural forms its language needs. It does not by itself guarantee that the wording is good, which is why human review still matters.
Can you certify your own translation?
Certification requirements depend on the country and document type. Check with the receiving authority whether certification is needed and who is qualified to provide it. For app strings, teams can use validation reports and reviewer sign-off, but check whether the receiving organization has specific requirements. Check the requirements of the receiving authority before relying on self-certification.