12 Most Useful Localization Lint Rules for Teams

A translated build can compile cleanly and still fail users. A missing format argument can crash a screen, an oversized German label can hide a primary action, and a copied English string can slip into a market-specific release. The most useful localization lint rules turn these predictable defects into build-time findings, when they are less expensive to fix and easier to assign.

Localization linting is not spell-checking for translated text. It is structured validation of source and target resources, metadata, placeholders, markup, locale conventions, and UI constraints. The right rule set depends on the formats and frameworks in use, but a small number of checks consistently prevent the failures that reach production.

Start with the most useful localization lint rules

The highest-value rules protect runtime behavior first, then translation completeness, then language quality and presentation. Treat errors that can break an application as build blockers. Use warnings for issues that require human judgment, such as a potentially long label or a term that may be valid in a specific product area.

1. Placeholder parity

Every target string should contain the same required placeholders as its source. This includes printf-style arguments such as `%s` and `%d`, ICU MessageFormat variables, .NET composite format items such as `{0}`, named template variables, and framework-specific interpolation syntax.

The rule must compare more than the number of tokens. `{0}` and `{1}` may have different types or meanings, and a translator can accidentally change `%1$s` to `%s`. Where a format supports type information, validate index, name, type, and required escaping. Missing or malformed placeholders should fail the build because they can cause runtime exceptions or incorrect customer data.

2. Markup and tag integrity

Localized HTML, XML, Markdown, XLIFF inline tags, and rich-text resources need balanced, valid markup. A translation that drops a closing tag, changes an attribute delimiter, or moves a protected link target can break rendering or create a security review issue.

Lint should verify paired tags, nesting, protected attributes, and nontranslatable elements. It should also distinguish text intended for translation from code-like content that must remain unchanged. For example, an HTML `href`, a Markdown image path, and a JSON property name are not translation targets simply because they appear beside translatable text.

3. Escaping and syntax validity

Resource formats have their own escaping rules. Apostrophes have special meaning in ICU messages, ampersands may mark access keys in desktop resources, backslashes matter in JSON, and line breaks can alter YAML or properties-file parsing.

A syntax rule should parse every generated target file using the same expectations as the consuming application. This is more reliable than scanning text with regular expressions alone. It catches malformed JSON, invalid XML entities, duplicate keys, unescaped control characters, and broken plural expressions before those files enter a package or deployment artifact.

4. Missing, empty, and source-equal translations

A complete language file is not necessarily translated. Lint for missing target entries, explicitly empty values, and targets identical to the source when the language normally differs from English. These cases should not all have the same severity.

An empty value may be intentional for a feature that is hidden in a locale. Source-equal text may be correct for brand names, technical acronyms, or short universal commands. A practical configuration allows approved exceptions through comments, statuses, or an exclusion list. Without that control, teams train themselves to ignore warnings, which defeats the purpose of linting.

Validate locale behavior, not just strings

A resource can be linguistically correct and still be wrong for the selected locale. Locale-aware rules protect the conventions encoded in dates, numbers, units, plural logic, and language metadata.

5. Locale code and fallback validation

Validate language tags against the project’s supported locale model. Catch invalid tags, inconsistent casing, unsupported script or region subtags, and resources that cannot resolve through the intended fallback chain.

This matters when `pt`, `pt-BR`, and `pt-PT` are handled differently, or when Chinese resources require script-aware handling such as `zh-Hans` and `zh-Hant`. Also check for duplicate resources that normalize to the same locale. A fallback problem may appear only on a device or tenant configured for a less common regional variant.

6. Plural and select-message coverage

Plural rules are a common source of defects because English has relatively simple categories. Other locales can require additional categories, while some frameworks use exact-number selectors or gender-based select expressions.

Lint should ensure that each plural message contains the categories required by the target locale and that source variables are preserved in every branch. It should also flag empty branches and inconsistent placeholders between branches. Do not require English plural categories in every locale without checking the message format and locale data your runtime actually uses.

7. Date, number, currency, and unit tokens

Hard-coded examples such as `12/03/2026`, `$99.00`, or `10 miles` are often translation defects disguised as copy. A rule can flag recognizable date, numeric, currency, and measurement patterns in translatable strings and require locale-aware formatting at runtime where appropriate.

This rule needs careful tuning. A support article may intentionally show a US-formatted example, while an application status message should normally receive a formatted value from code. Flagging is usually better than blocking unless the team has a strict resource convention.

Protect terminology and product consistency

Translation memory and terminology management improve consistency, but linting makes policy enforceable at the point where a resource changes. These checks are especially useful in products with frequent releases and multiple contributors.

8. Forbidden terms and required translations

A terminology rule can reject deprecated product names, unapproved feature labels, legacy legal language, and competitor references. It can also require an approved translation for a controlled term when it appears in a specific context.

Avoid simplistic global replacement logic. The word “account,” for example, may mean a user profile, a financial account, or a customer relationship. Scope terminology by locale, product, file path, or resource context, and allow approved inflections where the target language requires them.

9. Nontranslatable token protection

Product identifiers, command names, API fields, file extensions, code snippets, keyboard shortcuts, and placeholders should remain intact when required. Lint can compare protected tokens between source and target and identify additions, omissions, or unauthorized changes.

This is particularly valuable for technical documentation, configuration screens, and developer tools. Translating `config.json` or an API property such as `retryCount` makes instructions impossible to follow. At the same time, do not protect ordinary UI labels simply because they look technical. The rule should be driven by explicit token definitions and format awareness.

10. Accelerator and shortcut conflicts

Desktop applications and some web interfaces use access keys, often represented by an ampersand or underscore marker. Lint should verify that required access keys exist, the marker is escaped when literal, and controls within the same dialog do not use the same accelerator.

This check needs UI scope. A duplicate accelerator in unrelated windows is harmless; a duplicate in one menu is not. Visual editors and resource metadata can provide the context needed to validate the correct container rather than treating every file as one global surface.

Catch layout risks before visual QA

Automated linting cannot fully replace localized visual review. It can, however, prioritize the screens most likely to fail and enforce constraints that do not require subjective review.

11. Length and expansion thresholds

Flag translations that exceed a configured length, character expansion ratio, or pixel width where UI measurements are available. A fixed 20-character limit is rarely appropriate across every control. Button labels, table headers, mobile navigation items, and legal disclosures have different constraints.

Use source-to-target expansion thresholds as an early warning, not a universal rejection rule. German, Finnish, and Russian may expand naturally, while Chinese may use fewer characters but still create visual issues because of font metrics. The strongest implementation combines text rules with visual localization checks against actual layouts.

12. Duplicate, obsolete, and unused resource detection

Resource repositories accumulate dead strings, duplicate identifiers, stale translations, and keys no longer referenced by code. These are not only maintenance concerns. They increase translator workload, create inconsistent terminology, and make it harder to identify the strings that matter for a release.

Lint can compare resource keys against scanned code references, identify duplicate source values with divergent translations, and report entries marked obsolete but still shipped. Some dynamic key patterns cannot be resolved statically, so treat unused-resource findings as warnings until the project has reliable conventions for dynamic lookup.

Make linting part of the delivery pipeline

Run fast structural checks locally when developers edit resources, then run the full rule set in continuous integration before generating deployable outputs. Baseline existing findings during adoption so a mature repository does not fail because of years of inherited defects. New violations should be blocked even while the backlog is reduced incrementally.

Rules should report the file, resource key, locale, source value where safe to display, and the exact validation failure. A message such as “placeholder mismatch” is not enough. “fr-FR: `OrderReady` is missing `{orderNumber}`” gives a developer or translator a direct correction path.

Soluling can apply validation while scanning source resources and generating localized files, helping teams keep checks close to the formats and build process they already use. That proximity matters when one release includes application resources, help content, database data, and structured configuration files.

Start with placeholder parity, syntax validity, missing translations, plural coverage, and protected tokens. Then add terminology, accelerator, layout, and cleanup rules as the team establishes ownership for each finding. A useful lint rule is not the one that reports the most issues. It is the one that prevents a real defect without creating noise that people learn to ignore.