ESLint Vue I18n checks help application teams find missing translation keys, invalid message syntax, hard-coded text and risky dynamic lookup patterns before they reach production. The maintained @intlify ESLint plugin provides rules for Vue components and message resources, making static checks an effective first line of defense for multilingual user interfaces.
Developers searching for `@intlify/eslint-plugin-vue-i18n`, `no-missing-keys`, `no-dynamic-keys`, `valid-message-syntax` or Vue I18n CI validation can use this guide to connect individual warnings with real product behavior. It explains what the rules can check, how to verify configuration and why language accuracy still needs a qualified person.
Begin by confirming supported ESLint configuration, linting a known faulty component and making sure locale files are included. Then review missing and duplicate keys, plural syntax, dynamic identifiers, HTML safety and fallback. Complete the process with Unicode, accessibility, mobile layout and the actual target-language user journey before treating a release as ready.
- Use a supported configuration and demonstrate that one deliberate missing key is detected.
- Begin with recommended rules before applying strict optional policies.
- Fix user-impacting meaning and runtime problems as well as syntactic issues.
- Track exactly which files, locales and important user journeys were verified.
A practical first lint run
Once ESLint, Vue parsing and the internationalization plugin are configured for the project, run the commands below. A successful command on an unconfigured project is not evidence that localization rules ran. First insert a reversible missing-key test and confirm the diagnostic, then remove it and test the repaired component.
npx eslint .
npx eslint src/components/Example.vue1. Choose the right Vue I18n lint package
The maintained @intlify ESLint plugin covers localization mistakes in Vue code and message resources. Its rule identifiers use the @intlify/vue-i18n namespace. That naming distinction matters: installing an unrelated package or copying an outdated rule name can leave an apparently configured project without useful checks.
Read the plugin’s current installation instructions and confirm compatible versions of Vue, ESLint and other parsers. Enable a recommended baseline in a temporary branch. Use a known missing translation reference as a deliberate test case.
A working linter reports the known defect and stops reporting it when repaired. Save the package versions and configuration revision so another engineer can reproduce that result.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
2. Verify ESLint flat config
Modern ESLint projects often use eslint.config.js rather than older configuration files. Configuration order and file patterns can change which rules apply, especially when JavaScript, TypeScript, Vue SFCs and locale data live in different directories.
Examine the exact files covered by each block of configuration. Prefer supported examples from the package’s own documentation rather than copying a configuration from a different major release.
Lint a targeted component and a small resource file deliberately containing a syntax error. If no finding appears, fix file discovery or parsing before adding more rules.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
3. Start with the recommended policy
The plugin maintains recommended checks plus optional best-practice and stylistic rules. Starting with a supported preset reduces the risk of forgetting essential syntax checks, but it is not evidence that every translation is complete.
Review the recommended rules listed in the maintained documentation and assign ownership for each finding. Add stricter checks incrementally, recording exceptions that are justified by product behavior.
A recommended preset is a baseline, not a full release contract. A translation can be grammatically wrong while every enabled rule passes.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
4. Detect missing message keys
A button that calls a nonexistent translation key may display a fallback, a raw key name or an empty label. The no-missing-keys rule helps expose calls that fail to resolve against the catalogues it knows.
Create a deliberately misspelled key in a Vue component, run ESLint, then repair the reference to a reviewed message. Inspect the component in a target language afterward.
A spelling repair should not silently redirect a destructive action to a benign label. Confirm the message describes the actual user action.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
5. Find target locales missing entries
A key existing in the source-language catalogue does not mean it exists in French, German or Arabic files. The optional no-missing-keys-in-other-locales rule can enforce cross-locale coverage where required.
Choose supported locales explicitly and decide whether all must be complete or whether a documented fallback is permitted. Inspect findings from the rule against that policy.
Do not mark a target language complete simply because it falls back to English. Report which locale served the user-visible text.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
6. Review unused translations carefully
Unused resource keys increase translation maintenance, but they may still be referenced from dynamic features, server templates, emails or code outside the lint scope. The no-unused-keys rule is a starting signal.
Search the repository and runtime paths before deleting a reported entry. Keep a reviewed diff and a test for any feature that could still use the message.
Removing a genuinely unused key is useful housekeeping. Removing a key used by a hidden recovery flow can create a serious production defect.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
7. Avoid unconstrained dynamic keys
String concatenation such as a status prefix plus a database value can hide which messages an application needs. The no-dynamic-keys rule points to places where static coverage becomes difficult.
Use a finite mapping from allowed states to literal message keys when possible. For a legitimate dynamic family, document the domain of keys and add integration tests rather than disabling all safeguards.
A safe dynamic lookup is bounded and observable. A lookup built from arbitrary input is harder to reason about and harder to translate reliably.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
8. Make hard-coded English visible
A Vue template can include human-readable English that never goes through the localization catalogue. The no-raw-text rule can identify candidates for extraction into message resources.
Inspect each finding: button labels and instructional text usually need localization, while source-code examples, immutable identifiers and some brand names may be exceptions.
Extracted messages still need translator context and target-language review. The rule detects an engineering pattern, not the quality of the resulting prose.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
9. Handle brand names without noise
Some terms must remain unchanged across locales for legal, trademark or technical reasons. An aggressive raw-text rule can produce noisy findings if the team has not documented these cases.
Create narrowly scoped exceptions tied to the relevant component or literal, with a reason. Avoid disabling the rule globally just because it found one brand.
Revisit exemptions when the product changes. A string that was once a fixed product name may later become editable interface copy.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
10. Validate message syntax
A resource can be present while containing malformed interpolation, linked-message or plural syntax. The valid-message-syntax rule aims to catch these problems during development.
Insert a known invalid message in a test catalogue, run the linter, restore correct syntax and execute the message with realistic data.
Parsing success does not prove that tense, politeness or obligation survives translation. Have a language reviewer inspect the finished output.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
11. Check plural categories and examples
Plural messages vary across languages. An English singular/other pair should not be copied blindly to a locale with more grammatical distinctions.
Use the plugin’s valid-plural-forms policy where appropriate. Test counts such as zero, one, two, five and larger values against the target language’s actual grammar.
The numeric value must remain unchanged while the surrounding phrase changes. Review real outputs, not just catalogue structure.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
12. Keep locale names recognizable
A typo in a locale code or an unsupported regional tag may prevent a file from loading or trigger an unexpected fallback. The no-unknown-locale rule can reveal some such mistakes.
Compare the configured locales with filenames and real deployment behavior. Check one general language and a region-specific variant if supported.
A locale code is a stable resource identifier. Do not rename it by intuition or assume every country’s language choice is identical.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
13. Reject duplicate resource keys
Duplicate keys in locale data can shadow each other, causing the editor to show one value while the runtime resolves another. The no-duplicate-keys-in-locale rule helps reveal this ambiguity.
Create a tiny duplicate-key fixture and verify the rule reports it. Choose the correct translation under review and remove the extra entry without changing unrelated messages.
Unique identifiers improve predictability. The correct value must still be checked in the rendered page.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
14. Use consistent key formats
Inconsistent naming makes messages difficult to find and encourages duplicate content. The key-format-style rule can help apply a chosen convention across a team.
Agree on meaningful namespaces such as account.reset_error rather than copying every English sentence into a key. Migrate old names with coordinated code and catalogue changes.
Key formatting is a maintenance choice, not language quality. Avoid sweeping renames during an urgent safety fix.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
15. Single-file component messages
Vue SFCs can contain component-scoped locale blocks alongside application-level messages. That flexibility also means content can be excluded from linting or shadow a global resource.
Inspect rules relating to SFC language attributes and locale attributes. Use a known local message in two rendering contexts to establish where it comes from.
A reusable component should not silently display a message intended for a different action because two keys happen to share a name.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
16. Deprecation checks during upgrades
Vue I18n major-version changes can deprecate APIs and component patterns. The rules index includes deprecation checks, which help make migration work visible.
Read the target version’s migration guide and change calls deliberately. Exercise plural forms, linked messages, scoped translations and fallback behavior after migration.
An API change is not only a compiler matter. Users should receive equivalent meanings, actions and accessibility cues before and after the upgrade.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
17. Translation HTML and no-v-html
Placing translated output into v-html can introduce unsafe markup or unwanted structural changes. The plugin’s no-v-html rule is especially relevant where language resources and user data meet.
Prefer text rendering or application-controlled rich-text components. Keep tags and executable behavior out of translator-editable strings whenever possible.
A translated sentence is not a sanitization guarantee. Verify that punctuation and variable values cannot change HTML structure.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
18. No HTML embedded in messages
A localized string containing markup can be fragile across tools and difficult for translators to edit. The no-html-messages policy is useful when applications can express rich text structurally.
Move links and formatting into safe Vue components while providing translatable human-readable fragments. Review context so grammar remains natural when parts are reordered.
A bare less-than symbol in technical content may be legitimate text. Examine intent before suppressing or changing a finding.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
19. Interpolation variables as contracts
When a message expects a user name, price or count, the component must supply compatible data. A syntax-valid string can still render an undefined value or misleading number.
Test missing values, long accents, right-to-left names and formatted prices. Keep the field semantics stable while allowing target-language word order.
Do not translate the placeholder’s programmatic identity or embed private customer data in test fixtures.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
20. Different error states need different messages
A failed payment, a pending payment and a canceled payment may sound similar but require different user actions. Reusing one vague key can create confusion even if lint passes.
Map each state to a reviewed message and test each branch. Have the product owner approve the source meaning, especially for irreversible actions.
A correct lookup is necessary but not sufficient. Verify what the user thinks happened and what action the screen permits next.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
21. Fallback policy must be explicit
Runtime locale fallback can keep an interface usable when a target resource is missing, but it may mix languages and conceal unfinished translation work.
Document the fallback hierarchy and decide which high-impact screens require complete target-language coverage. Use missing-key checks to find unintentional gaps.
Keep user-facing language support promises aligned with the reality of available messages. A fallback is not an approved translation.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
22. Directory coverage and external assets
Some products store messages in packages, shared libraries, CMS exports or external files. A local ESLint run may not inspect them at all.
Identify every source of user-facing strings and assign a verification method. Confirm that locale files outside src are discovered and that generated catalogues have a separate check.
Publish coverage boundaries in the release checklist; a green report can be entirely accurate for the small subset it examined.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
23. Monorepo packages and ownership
Several Vue applications may share a library of message keys while keeping different design and region requirements. A single lint command from the wrong package root can miss one consumer.
Run checks with the proper package configuration and locale paths. Test a shared component and an application-specific screen.
Record which team owns a key and which products use it so a change in one app does not accidentally break another.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
24. TypeScript and parser compatibility
Vue components may use TypeScript script blocks alongside template expressions. Parser misconfiguration can create errors unrelated to language or omit parts of the codebase.
Use supported combinations of Vue parsers and ESLint rules. Confirm known test cases are caught in JavaScript and TypeScript components.
Fix compatibility issues before reclassifying all localization findings as noise. The test scope must be trustworthy.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
25. Autofixes need review
Stylistic rules may be fixable automatically, but changing source copy, key meaning or plural structure involves more than formatting.
Apply autofix only on a review branch, inspect the diff and keep mechanical changes separate from translated text edits.
A green autofix result should never be described as editorial sign-off. The affected screen still needs testing.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
26. Introduce rules without overwhelming teams
A long-established application may have many historical findings. Enabling every rule as a fatal error at once can produce a pipeline nobody trusts.
Begin with high-risk syntax and missing-key failures, triage existing debt and add stricter best practices with explicit owners and milestones.
A small, working quality gate is better than a large rule list that the team learns to ignore.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
27. Make CI failures actionable
CI output should point to a file, key, rule and severity. A generic failure banner does not tell developers whether to fix code or ask for a translation review.
Pin tool versions, run npx eslint . in a clean environment and preserve concise logs. Ensure an intentionally broken fixture fails during a controlled pipeline test.
Security warnings, payment messages and account recovery need human approval even if the static build turns green.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
28. Unicode and script coverage
A resource with accented, CJK or right-to-left text can be syntactically valid while fonts, bidirectional punctuation or line wrapping make the interface unusable.
Test representative target scripts in real browsers and at realistic viewport sizes. Check mixed-script identifiers, focus order and assistive technologies.
The linter checks patterns in code and catalogues. The browser and a reader must verify the visual and functional experience.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
29. Accessibility labels and errors
Screen readers rely on meaningful names, descriptions and correctly associated status messages. These may be hard-coded or poorly translated even when visible text looks fine.
Inspect translated ARIA labels, form errors, live announcements and keyboard navigation. Test with assistive technology in relevant locales.
A missing-key rule cannot prove that the right message is announced by the right control at the right time.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
30. Mobile width and text expansion
English labels may be short while accurate translations require substantially more characters. Narrow buttons, dialogs and navigation bars can clip text despite perfect resource syntax.
Use pseudolocalization or deliberately expanded test strings early, then test reviewed translations on common mobile sizes.
The right solution is often flexible layout, not forcing translators to shorten critical instructions until they lose meaning.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
31. Regional terminology and tone
A message may be grammatical yet inappropriate for a particular market’s banking, administrative or conversational conventions. Linting is not equipped to decide that question.
Assign regional reviewers to important flows, provide screenshots and ask whether the action and level of formality remain clear.
Treat high-impact changes as product decisions rather than asking the linter to approve or reject cultural nuance.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
32. A test case for false positives
Some static rules cannot resolve computed keys or indirect references conclusively. A warning may be legitimate even when observed runtime behavior works.
Build a minimal reproduction and document a narrowly scoped exception with a matching integration test. Avoid disabling an entire rule for a single unusual design.
Revisit each exception after refactors. Static analysis improves when teams understand where its view of the system ends.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
33. Source text and translation provenance
A target phrase might be fluent but based on an outdated source sentence. Key validity cannot reveal a changed policy or newly required consent.
Associate important translations with their source revision, reviewed meaning and target locale. Protect security and financial wording with additional sign-off.
A resource has two kinds of correctness: it must load, and it must preserve the actual current promise to users.
Separate what the static analyzer knows from what a person experiences. Resource existence, parser validity, message accuracy and accessible layout are different properties. A complete review needs the appropriate test and owner for each property.
34. Release acceptance evidence
Before release, establish a clean lint result for the intended scope, explicit exceptions, locale completeness, valid runtime messages and human sign-off for meaning.
Run real task flows in at least one non-source locale, including errors, accessibility, mobile and formatting. Keep versioned evidence.
The strongest valid claim is that specified checks passed for specified files and locales, not that all languages are universally perfect.
Give unusual attention to payment, identity, permission, medical or safety-related text. An ordinary rule can flag a technical defect, but a wrong obligation can survive every automated check. Seek informed source and target-language review before release.
35. Keep the workflow maintainable
Localization coverage is not a one-time achievement. New components, languages, dependencies and product policies introduce new risks continually.
Add lint review to ordinary pull requests, document rule owners and run known-negative tests after major tool upgrades. Keep exceptions limited.
Make it easy for translators and developers to collaborate without giving either group responsibility for checks outside its expertise.
Observe both the intended scenario and a failure path. A happy-path English screen can conceal a missing French error, a long German label or right-to-left punctuation trouble. Representative target-locale testing makes the result credible.
36. Quick decision framework
When a finding appears, ask whether it concerns resource existence, syntax, application behavior, source meaning or target-language quality. Each category has a different owner and appropriate test.
Repair the smallest root cause, rerun the static check and reproduce the relevant screen. Escalate high-risk content to the product owner and qualified language reviewer.
A useful workflow turns an alarming list of warnings into concrete, verifiable actions rather than superficial compliance.
Run a deliberate counterexample in a disposable branch. A useful localization check should catch a known failure and stop reporting it after the correct fix. This simple exercise tells reviewers more about coverage than a long list of enabled rules with no observed behavior.
37. A reader-first final checklist
A person using the translated product wants to understand what happened, what comes next and which button is safe to press. That human goal should guide every rule selection.
Verify the actual locale, the presence of messages, the validity of resources, the behavior of dynamic values and the accessibility of important screens.
Keep a record of what was tested and what remains incomplete. Clarity about limitations is part of a trustworthy multilingual release.
Attach the finding to a real user action. Record the component, message key, source meaning, target locale and actual display. Another engineer should be able to reproduce the result without needing the original author to explain undocumented assumptions.
Worked example: a multilingual booking and cancellation form
Consider a Vue reservation form that appears complete in English. Its French error catalogue misses a cancellation key, its confirmation label is hard-coded, a developer builds status keys by concatenating arbitrary server values, and a translated error contains a malformed interpolation token. These problems belong to distinct rule families, and some will appear only when a customer makes a change or cancels.
First confirm that ESLint discovers the Vue component and locale resources. Introduce one known bad key to validate the rule configuration, then remove the fixture. Map allowable reservation states to literal keys and ensure a reviewer can inspect each sentence. Repair the interpolated value and ask a qualified French reviewer to compare the actual cancellation consequence with the approved English source. Test the complete booking and cancellation flow, including payment effects where relevant, and inspect errors in mobile and keyboard-navigation contexts.
Keep a small release record with the lint result, file revision, resolved locale, screenshots and meaningful sign-offs. The practical value of linting is the opportunity to catch engineering defects early, leaving language reviewers more attention for accuracy and usability.
Frequently asked questions
What is the maintained package name?
The official package is @intlify/eslint-plugin-vue-i18n. Its rules use the @intlify/vue-i18n namespace; review the current rule index and setup guide before copying snippets from an older major version.
Why is my missing key not reported?
Your ESLint setup may be excluding the component or locale file, a rule may not be enabled, or the key may be constructed in a way the static analysis cannot resolve. Test a simple known literal reference.
Is every warning a translation problem?
No. Some findings concern source structure, configuration, parser behavior or risky runtime patterns. Categorize each before assigning it to a developer, translator or product owner.
Is a fallback string a complete translation?
Not necessarily. A fallback can keep a screen usable, but it should be recorded as a deliberate behavior rather than reported as approved target-language coverage.
Can ESLint approve language quality?
No. It can check resource and source patterns, but human reviewers must judge the accuracy, formality, cultural appropriateness and consequences of important sentences.
Should dynamic keys be banned?
Prefer a small, explicit mapping when possible. A genuinely necessary dynamic family needs a documented domain of allowed identifiers and runtime tests.
What about HTML in translation files?
Avoid letting translator-editable strings control executable markup. Keep structure in application components and render translated text safely under the project’s security model.
Can I use autofix for everything?
No. Some structural violations can be repaired mechanically, but the meaning of a source instruction and its translated version require editorial decisions.
How should we test Arabic or Hebrew?
Use real screens in relevant locales, including right-to-left layout, mixed identifiers, punctuation, assistive technology and small viewports. Source-file syntax alone does not establish usability.
What should the release gate include?
A reproducible lint run, defined scope, documented exceptions, locale coverage, runtime examples and human review of sensitive messages. Separate those items in the evidence record.
Official documentation and further reading
Consult the maintained rules index at https://eslint-plugin-vue-i18n.intlify.dev/rules/ and the individual no-missing-keys and no-dynamic-keys rules under that site. The official ESLint plugin configuration guide is at https://eslint.org/docs/latest/use/configure/plugins . Keep the installed plugin version, lint scope and user-facing examples together as a practical release record.