How do you localize Vale CLI documentation and interpret prose-linting diagnostics without rewriting code or imposing one language’s editorial rules on every translation? This Vale CLI localization guide explains the `.vale.ini` configuration, `StylesPath`, `BasedOnStyles`, external style packages, project vocabularies, rule messages, severity levels, command examples, continuous integration and Unicode quality assurance. It is written for translators, technical writers, documentation engineers and multilingual product teams worldwide.
Vale is a configurable prose linter, not a machine-translation engine and not a universal grammar judge. Its results express particular style rules against particular source material. A warning about a preferred term can be excellent advice for one English-language documentation set and wholly unsuitable for an otherwise correct French, Japanese or Arabic text. The reader’s task is to discover which policy produced a finding, protect commands and configuration keys, and decide whether the corresponding target-language rule exists.
Start with the source document, its language, the Vale version and the active styles. Keep literal commands such as `vale`, configuration names such as `MinAlertLevel`, file patterns, YAML rule keys and package identifiers unchanged in executable examples. Translate explanations, review instructions and appropriate human-facing diagnostic text, then verify that Unicode punctuation, diacritics, right-to-left scripts and normalization do not change a copied file or rule. A practical workflow is more useful than a list of translated error strings.
Quick answers before you begin
- Use Vale to enforce a chosen editorial style, not to certify factual accuracy or translation equivalence.
- Locate `.vale.ini` and resolve the active `StylesPath` before interpreting a finding.
- Distinguish `BasedOnStyles`, style packages, vocabulary entries and individual YAML rules.
- Preserve command names, rule identifiers, paths and YAML keys in copyable examples.
- Test target-language content with a rule set that is valid for that language.
- Require a human meaning review alongside automated prose checks.
This guide concerns the Vale prose-linting executable and how to write, translate and validate documentation about it. Spelling-dictionary workflows belong to CSpell; natural-language plugin rules belong to textlint; Markdown structure rules belong to markdownlint. Those tools can complement Vale, but their policies and diagnostic promises should not be merged.
A dependable starting sequence
A practical first exercise uses a short Markdown page and a simple `.vale.ini` that defines a styles directory and selects a style for Markdown. Run `vale README.md`, note the actual installed version and observe the rule name, alert severity and source span. Make one small change, rerun and compare. Do not assume that a public style package, a downloaded vocabulary or a local custom rule is installed merely because a guide names it.
Capture the installed version, the source file and the exact command before rewriting the instructions. Work in a reviewable copy. Identify which strings are executable, which are configuration data, which are human-facing explanation and which are external facts that the tool cannot verify. This prevents a translation from accidentally altering the test while describing it.
Why Vale belongs in a translation workflow
Vale can enforce consistent terminology, preferred constructions and style choices across writers. A localized release still needs separate semantic and domain review because a style pass is not a certification of meaning. Treat the reported result as evidence about one configured run, not as a universal judgement about language. The original text, the exact input and the active policy belong together.
Worked situation. A team receives a clean Vale report for an English guide and decides its Spanish translation is ready without checking the product’s interface language or warnings. If a reviewer disagrees, ask which observable condition differs rather than debating the elegance of a phrase. Differences in input, configuration and execution environment can explain apparently contradictory results.
Common mistake. A zero-warning result can be produced by an inactive rule set as easily as by good writing; the report must be interpreted against configuration. Overgeneralizing from one file can conceal a bad configuration or an excluded directory. A clean report is meaningful only for the files that were actually evaluated.
Practical check. Test one intentionally prohibited phrase in the target document and verify that the relevant rule can identify it. Run the same check before and after the edit, and inspect the exact change in the report. Record unresolved exceptions with a reason rather than hiding them.
Install and version the executable
Vale is available for major desktop platforms and can run in local or automated documentation builds. Command syntax and available features should be checked against the version actually installed in that project. Think about the reader who must reproduce the outcome without knowing the author. A useful explanation names the relevant file, command, policy and expected observation.
Worked situation. A tutorial copied from an older repository uses an option a new teammate cannot find in their executable’s help output. Use a small representative fixture before changing a repository-wide setting. One normal example and one deliberate counterexample reveal whether the proposed rule is too broad.
Common mistake. Treating every command failure as a translation error hides version drift and installation problems. A false positive can be expensive when it becomes a blanket exception. Prefer a documented scoped decision over weakening checks for every file.
Practical check. Record `vale –version` and consult `vale –help` before instructing readers to adopt flags from a different release. Ask a second reader to locate the underlying source using only the translated instruction. If they cannot, improve the reference instead of simplifying away the evidence.
Understand `.vale.ini`
The `.vale.ini` file tells Vale where styles are located and which rules apply to document patterns. It contains working configuration, not sentences for translation. Separate a descriptive statement from an instruction. Descriptions say what the tool found; instructions tell a person what to inspect or change next.
Worked situation. A Japanese-language quickstart replaces `StylesPath` with a Japanese phrase inside an INI example, leaving a reader with a file that no longer configures Vale. Describe the user’s next step in ordinary language beside the untouched example. This makes the instructions useful to people who are not comfortable reading terminal output.
Common mistake. The visual similarity of configuration keys to English words invites harmful localization of literal syntax. An error message translated as a command can send a reader down the wrong path. Keep instructions grammatical and clearly distinguish advice from the observed condition.
Practical check. Show unchanged INI keys in monospace; place translated descriptions immediately above the sample. Keep one positive and one negative example in a test fixture. They should show what the team wants the rule to catch and what it should leave alone.
Resolve `StylesPath`
`StylesPath` identifies the styles directory. Relative paths depend on the project arrangement, so moving a tutorial file can change what a reader believes is available. Preserve the boundary between human-readable prose and machine-consumed tokens. A visually attractive translation can still be wrong if a copied identifier no longer works.
Worked situation. A company keeps style rules under `.vale/styles` while a copied example points to `styles`; every document appears to pass because the intended rules did not load. Test the operation on a copy or reviewable branch before applying an automatic change. Documentation should not turn a demonstration into an uncontrolled write.
Common mistake. A path in a screenshot is evidence of one checkout, not a portable universal directory. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Inspect the real directory and try a deliberate failing sentence before trusting a clean run. Confirm that a copied command executes with the intended working directory and an appropriate non-destructive mode. An explanation is incomplete when its reproduction steps are unsafe.
Select `BasedOnStyles` intentionally
`BasedOnStyles` selects the rule collections for a configured file scope. A named external style is not automatically available just because a prose guide lists it. Prefer a narrowly verified claim to a reassuring generality. Style and quality checks are useful signals, but they rarely prove meaning, accessibility or factual correctness.
Worked situation. An onboarding guide promises that an English style package will check Italian documentation even though the selected rules target English usage. Check whether the diagnostic points to source text, generated output or metadata. These may require different owners and different ways to repair the problem.
Common mistake. Calling every style pack globally applicable makes translation maintenance unpredictable and can create false positives. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Document the language and purpose of each enabled style and test a phrase its rules actually recognize. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Separate packages from local custom rules
Vale can use packaged styles as well as project-authored YAML rules. Package availability and syncing are operational steps; the words explaining those steps are prose. Apply the same vocabulary to the command, the diagnostic and the remedial step. Consistent naming reduces handoff errors between translators, engineers and reviewers.
Worked situation. A new contributor runs a lint command, receives missing-style feedback and assumes the translation has a terminology defect. Compare the before and after versions as a reader would. The absence of a linter warning cannot show whether a warning sentence remains safe or a translation remains accurate.
Common mistake. A missing package should not be glossed as an incorrect word in a document. Treat tool versions as part of the evidence. If an option or result seems unfamiliar, consult the installed version’s help before documenting it as permanent behavior.
Practical check. Check the project’s package configuration and run `vale sync` when the configured workflow requires installed packages. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Explain `vale sync` conservatively
`vale sync` is used to obtain configured style packages. It does not translate files and is not a replacement for reviewing downloaded rule choices or licensing and maintenance needs. Identify who owns the rule before changing it. Some language belongs to an organization’s editorial standard; other language comes from a third-party configuration or an API.
Worked situation. A team tells writers that synchronization has harmonized all localizations, when it has only prepared style resources. Keep a small audit trail: source sentence, target sentence, rule identifier, decision and reviewer. It prevents the same exception from becoming an unexplained convention.
Common mistake. The verb ‘sync’ is easy to overtranslate as editorial agreement or automatic revision. Do not assume an apparent word boundary is a semantic boundary. Tokenizers, markup parsers and regular expressions may segment text differently from humans.
Practical check. State plainly which packages are expected and verify a subsequent check actually loads the intended rules. Ensure the recommended fix changes the relevant content, not merely the tool’s tolerance for the content. Suppressing an alert is a different decision from correcting a problem.
Read diagnostic severity carefully
Rules may report suggestion, warning or error, and `MinAlertLevel` affects which alerts are visible. Visibility and process exit status are different questions, so explain them separately. Record enough context to distinguish two similar reports. A path, line number and rule name usually provide better evidence than a translated headline on its own.
Worked situation. A documentation pipeline hides suggestions to reduce noise, and the release note claims no style issues exist. Include a counterexample where the apparent rule should not apply. That teaches the difference between the tool’s mechanical boundary and the editor’s judgment.
Common mistake. Concealing low-severity output is not evidence that the underlying text changed. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Inspect the configured minimum level and compare it with one deliberately triggered example at each relevant severity. Record which warning remains after the repair and why. A complete review can reasonably accept a justified exception without pretending the exception does not exist.
Understand `MinAlertLevel` boundaries
`MinAlertLevel` is a filtering preference that helps teams decide how much output to show. Its name is a literal configuration key; localize its explanation instead. Treat the reported result as evidence about one configured run, not as a universal judgement about language. The original text, the exact input and the active policy belong together.
Worked situation. A translator changes the key’s capitalization and uses a translated value for a severity, leaving a configuration that reviewers cannot reproduce. If a reviewer disagrees, ask which observable condition differs rather than debating the elegance of a phrase. Differences in input, configuration and execution environment can explain apparently contradictory results.
Common mistake. A readable explanation cannot rescue an invalid setting or silently suppressed important alert. Overgeneralizing from one file can conceal a bad configuration or an excluded directory. A clean report is meaningful only for the files that were actually evaluated.
Practical check. Copy the exact key and supported level values from the versioned documentation; lint a fixture to show the effect. Run the same check before and after the edit, and inspect the exact change in the report. Record unresolved exceptions with a reason rather than hiding them.
Build an existence rule
A Vale `existence` rule can identify undesirable expressions in selected text. The regex or token expression describes what the rule can match, not every human interpretation of the phrase. Think about the reader who must reproduce the outcome without knowing the author. A useful explanation names the relevant file, command, policy and expected observation.
Worked situation. A style team bans a phrase in headings but neglects to scope its rule, so body text is flagged unexpectedly. Use a small representative fixture before changing a repository-wide setting. One normal example and one deliberate counterexample reveal whether the proposed rule is too broad.
Common mistake. An unscoped pattern can punish valid quotations, code examples or proper names. A false positive can be expensive when it becomes a blanket exception. Prefer a documented scoped decision over weakening checks for every file.
Practical check. Create both a matching and a non-matching fixture and confirm the intended scope before documenting the rule. Ask a second reader to locate the underlying source using only the translated instruction. If they cannot, improve the reference instead of simplifying away the evidence.
Create substitution guidance
A substitution rule offers a preferred replacement for a detected expression. The suggestion only has authority where the project style guide approves that replacement. Separate a descriptive statement from an instruction. Descriptions say what the tool found; instructions tell a person what to inspect or change next.
Worked situation. A translator automatically replaces ‘master’ in an API identifier with a preferred natural-language synonym; sample code no longer matches the product. Describe the user’s next step in ordinary language beside the untouched example. This makes the instructions useful to people who are not comfortable reading terminal output.
Common mistake. A recommended editorial substitute can be unsafe inside identifiers, names or user-visible product settings. An error message translated as a command can send a reader down the wrong path. Keep instructions grammatical and clearly distinguish advice from the observed condition.
Practical check. Keep a do-not-translate term list and verify any substitution against actual interface labels. Keep one positive and one negative example in a test fixture. They should show what the team wants the rule to catch and what it should leave alone.
Scope checks to headings or text
Vale supports rule scopes, such as headings rather than all text, depending on rule type. This makes the location of a diagnostic meaningful. Preserve the boundary between human-readable prose and machine-consumed tokens. A visually attractive translation can still be wrong if a copied identifier no longer works.
Worked situation. A heading punctuation rule flags a translated sentence in a note because the author forgot to define the rule scope. Test the operation on a copy or reviewable branch before applying an automatic change. Documentation should not turn a demonstration into an uncontrolled write.
Common mistake. A sentence-level finding should not be described as a document-wide prohibition. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Check a heading fixture and a prose fixture separately, then show readers exactly which boundary the rule enforces. Confirm that a copied command executes with the intended working directory and an appropriate non-destructive mode. An explanation is incomplete when its reproduction steps are unsafe.
Keep YAML rules executable
YAML rule files use keys such as `extends`, `message`, `scope`, `level` and `tokens`. The message may be human-facing, while the keys are syntax. Prefer a narrowly verified claim to a reassuring generality. Style and quality checks are useful signals, but they rarely prove meaning, accessibility or factual correctness.
Worked situation. An editor translates the YAML `tokens` key as if it were normal prose, making a previously working custom style invalid. Check whether the diagnostic points to source text, generated output or metadata. These may require different owners and different ways to repair the problem.
Common mistake. One altered key can make the entire example misleading even when its explanation is elegant. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Validate YAML parsing and run Vale against a known match after any localized documentation edit. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Write clear diagnostic messages
A rule’s message should name the detectable problem and suggest an actionable change without claiming that every instance is incorrect in context. Apply the same vocabulary to the command, the diagnostic and the remedial step. Consistent naming reduces handoff errors between translators, engineers and reviewers.
Worked situation. An alert reading ‘This is unprofessional’ is shown to writers whose approved locale uses a different convention; they cannot tell what to change. Compare the before and after versions as a reader would. The absence of a linter warning cannot show whether a warning sentence remains safe or a translation remains accurate.
Common mistake. Moralizing language confuses a chosen policy with a universal standard of good writing. Treat tool versions as part of the evidence. If an option or result seems unfamiliar, consult the installed version’s help before documenting it as permanent behavior.
Practical check. Rewrite the message to identify a term, pattern or structure and link to the rationale for the rule. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Use links to source guidance
Style-rule guidance links help writers understand why an alert exists. A localization should not replace the official rationale with an unrelated summary. Identify who owns the rule before changing it. Some language belongs to an organization’s editorial standard; other language comes from a third-party configuration or an API.
Worked situation. A localized diagnostics panel links ‘use active voice’ to an English-only page while the target translation requires a different sentence structure. Keep a small audit trail: source sentence, target sentence, rule identifier, decision and reviewer. It prevents the same exception from becoming an unexplained convention.
Common mistake. Treating an external style guide as law for every locale creates a hidden policy conflict. Do not assume an apparent word boundary is a semantic boundary. Tokenizers, markup parsers and regular expressions may segment text differently from humans.
Practical check. Specify the locale and style-owner decision; provide a target-language rationale when an approved one exists. Ensure the recommended fix changes the relevant content, not merely the tool’s tolerance for the content. Suppressing an alert is a different decision from correcting a problem.
Manage vocabulary without confusing it with translation
Vale vocabularies can accept or reject terms according to project rules. Acceptance is not proof that a word is suitable for every sentence or locale. Record enough context to distinguish two similar reports. A path, line number and rule name usually provide better evidence than a translated headline on its own.
Worked situation. A product term is accepted in English and added indiscriminately to all target-language documentation, including where the official UI uses a different term. Include a counterexample where the apparent rule should not apply. That teaches the difference between the tool’s mechanical boundary and the editor’s judgment.
Common mistake. A vocabulary exception can hide a terminology inconsistency rather than solve it. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Build a terminology record with source string, approved target form, context, version and reviewer. Record which warning remains after the repair and why. A complete review can reasonably accept a justified exception without pretending the exception does not exist.
Protect brand and API terminology
Product names, command tokens and API properties may have mandated casing and spelling. The editorial guide should explicitly separate these from ordinary sentences. Treat the reported result as evidence about one configured run, not as a universal judgement about language. The original text, the exact input and the active policy belong together.
Worked situation. The translated manual lowercases a case-sensitive header value to match house capitalization rules, and the example breaks. If a reviewer disagrees, ask which observable condition differs rather than debating the elegance of a phrase. Differences in input, configuration and execution environment can explain apparently contradictory results.
Common mistake. Natural-language style rules are not permissions to modify machine interfaces. Overgeneralizing from one file can conceal a bad configuration or an excluded directory. A clean report is meaningful only for the files that were actually evaluated.
Practical check. Compare copyable examples character for character with the canonical API or CLI reference. Run the same check before and after the edit, and inspect the exact change in the report. Record unresolved exceptions with a reason rather than hiding them.
Respect quoted text and code fences
Documentation often quotes messages or includes code that a prose linter should not edit as natural language. Applicable ignore or scoping configuration needs careful testing. Think about the reader who must reproduce the outcome without knowing the author. A useful explanation names the relevant file, command, policy and expected observation.
Worked situation. An automated replacement modifies a shell script inside a fenced code block when the writer intended only to tidy nearby prose. Use a small representative fixture before changing a repository-wide setting. One normal example and one deliberate counterexample reveal whether the proposed rule is too broad.
Common mistake. A broad ignore can conceal genuinely user-facing text, while a narrow one can corrupt copied syntax. A false positive can be expensive when it becomes a blanket exception. Prefer a documented scoped decision over weakening checks for every file.
Practical check. Prepare paired examples with ordinary prose and code; check which tokens the active rule sees. Ask a second reader to locate the underlying source using only the translated instruction. If they cannot, improve the reference instead of simplifying away the evidence.
Unicode normalization in rule matches
The same visible accented word can have different underlying Unicode sequences. Regex and token matching need representative normalization tests when targeting multilingual text. Separate a descriptive statement from an instruction. Descriptions say what the tool found; instructions tell a person what to inspect or change next.
Worked situation. A French product term displays correctly but fails a vocabulary test when entered with decomposed combining accents. Describe the user’s next step in ordinary language beside the untouched example. This makes the instructions useful to people who are not comfortable reading terminal output.
Common mistake. A screenshot cannot reveal whether two visually identical strings contain different code points. An error message translated as a command can send a reader down the wrong path. Keep instructions grammatical and clearly distinguish advice from the observed condition.
Practical check. Compare NFC and NFD forms in a controlled fixture and record the behavior of the installed rule engine. Keep one positive and one negative example in a test fixture. They should show what the team wants the rule to catch and what it should leave alone.
Right-to-left text and punctuation
Arabic, Hebrew and mixed-script documents can display punctuation and embedded commands in a visually surprising order. The source and displayed result must both be checked. Preserve the boundary between human-readable prose and machine-consumed tokens. A visually attractive translation can still be wrong if a copied identifier no longer works.
Worked situation. A copied command in an RTL paragraph appears reversed on screen, and a writer retypes it according to the display rather than the actual character sequence. Test the operation on a copy or reviewable branch before applying an automatic change. Documentation should not turn a demonstration into an uncontrolled write.
Common mistake. Visual order is not necessarily the logical character order used by a shell or parser. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Inspect code points, isolate literal commands typographically and test copying from the rendered documentation. Confirm that a copied command executes with the intended working directory and an appropriate non-destructive mode. An explanation is incomplete when its reproduction steps are unsafe.
Preserve line references and filenames
Diagnostic paths and locations connect a report to source files; they should normally remain literal even when surrounding explanatory text is translated. Prefer a narrowly verified claim to a reassuring generality. Style and quality checks are useful signals, but they rarely prove meaning, accessibility or factual correctness.
Worked situation. A translator converts a filename into a natural-language label, making the error impossible to find in a multilingual repository. Check whether the diagnostic points to source text, generated output or metadata. These may require different owners and different ways to repair the problem.
Common mistake. Rewording evidence identifiers disconnects readers from what the tool actually checked. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Make the path and line location copyable, and give a separate explanation of their meaning. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Align rule messages with glossary terms
One approved concept should normally have one stable target-language label within a product. A Vale alert is part of that vocabulary ecosystem but does not own every term. Apply the same vocabulary to the command, the diagnostic and the remedial step. Consistent naming reduces handoff errors between translators, engineers and reviewers.
Worked situation. The documentation calls a setting ‘profile’ while the localized interface calls it ‘policy set’, so users cannot find the command referenced by a warning. Compare the before and after versions as a reader would. The absence of a linter warning cannot show whether a warning sentence remains safe or a translation remains accurate.
Common mistake. Elegant synonyms can be harmful in troubleshooting instructions that depend on exact UI labels. Treat tool versions as part of the evidence. If an option or result seems unfamiliar, consult the installed version’s help before documenting it as permanent behavior.
Practical check. Review terms against the current interface, help text and localization glossary before merging. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Design an editorial CI gate
Continuous integration can run Vale on a defined file set and treat selected severities as failures. The release policy must state its scope and its limits. Identify who owns the rule before changing it. Some language belongs to an organization’s editorial standard; other language comes from a third-party configuration or an API.
Worked situation. A repository enables Vale for English Markdown but advertises that every translated page passed language quality assurance. Keep a small audit trail: source sentence, target sentence, rule identifier, decision and reviewer. It prevents the same exception from becoming an unexplained convention.
Common mistake. The job can be green while untranslated files or locales were never included in the inputs. Do not assume an apparent word boundary is a semantic boundary. Tokenizers, markup parsers and regular expressions may segment text differently from humans.
Practical check. Inspect file patterns and language-specific job matrices, then publish what was actually checked. Ensure the recommended fix changes the relevant content, not merely the tool’s tolerance for the content. Suppressing an alert is a different decision from correcting a problem.
Interpret editor integrations
Editors may display inline alerts derived from the same rules as a CLI run, but the surrounding interface and path mapping can change what a contributor sees. Record enough context to distinguish two similar reports. A path, line number and rule name usually provide better evidence than a translated headline on its own.
Worked situation. A writer reports a problem in an editor overlay while CI shows no matching alert because different configuration files were loaded. Include a counterexample where the apparent rule should not apply. That teaches the difference between the tool’s mechanical boundary and the editor’s judgment.
Common mistake. Assuming all tools use identical settings prevents the team from diagnosing a real divergence. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Compare version, configuration root, source path and relevant rule across editor and command line. Record which warning remains after the repair and why. A complete review can reasonably accept a justified exception without pretending the exception does not exist.
Review false positives rather than muting whole styles
False positives are expected when statistical or pattern-based language checks meet specialized terminology. A narrowly justified exception may be appropriate. Treat the reported result as evidence about one configured run, not as a universal judgement about language. The original text, the exact input and the active policy belong together.
Worked situation. A medical guide repeatedly flags a clinically correct term, and a maintainer disables the entire medical style pack for convenience. If a reviewer disagrees, ask which observable condition differs rather than debating the elegance of a phrase. Differences in input, configuration and execution environment can explain apparently contradictory results.
Common mistake. Suppressing all checks trades one local inconvenience for invisible future errors. Overgeneralizing from one file can conceal a bad configuration or an excluded directory. A clean report is meaningful only for the files that were actually evaluated.
Practical check. Reproduce the exact term in context and document a scoped exception or vocabulary entry with owner approval. Run the same check before and after the edit, and inspect the exact change in the report. Record unresolved exceptions with a reason rather than hiding them.
Write meaningful translator handoffs
A completed handoff should list executable tokens, editable prose, applicable locale rules, unresolved findings and verification evidence. This permits a second team to continue safely. Think about the reader who must reproduce the outcome without knowing the author. A useful explanation names the relevant file, command, policy and expected observation.
Worked situation. A contract translator receives only screenshots of red underlines and changes the glossary without knowing the `.vale.ini` that produced the alert. Use a small representative fixture before changing a repository-wide setting. One normal example and one deliberate counterexample reveal whether the proposed rule is too broad.
Common mistake. Without policy and input context, the next reviewer may fix the wrong problem confidently. A false positive can be expensive when it becomes a blanket exception. Prefer a documented scoped decision over weakening checks for every file.
Practical check. Provide a source excerpt, expected rendered wording, installed version and the rule or style name. Ask a second reader to locate the underlying source using only the translated instruction. If they cannot, improve the reference instead of simplifying away the evidence.
Handle multilingual mixed-language pages
A page can contain English interface labels, Japanese explanatory text and German legal quotations. No single prose rule set necessarily handles all three parts well. Separate a descriptive statement from an instruction. Descriptions say what the tool found; instructions tell a person what to inspect or change next.
Worked situation. A writer tries to make every quoted English interface label satisfy Japanese typography rules, changing the official product terms. Describe the user’s next step in ordinary language beside the untouched example. This makes the instructions useful to people who are not comfortable reading terminal output.
Common mistake. Uniform visual styling can be incompatible with faithful quotation and copyable commands. An error message translated as a command can send a reader down the wrong path. Keep instructions grammatical and clearly distinguish advice from the observed condition.
Practical check. Segment the document by function and language; specify which spans are subject to which checks. Keep one positive and one negative example in a test fixture. They should show what the team wants the rule to catch and what it should leave alone.
Escalate meaning-sensitive findings
Editorial linters do not know whether a dosage, contractual prohibition or safety warning has changed meaning. Such material deserves expert review even after style cleanup. Preserve the boundary between human-readable prose and machine-consumed tokens. A visually attractive translation can still be wrong if a copied identifier no longer works.
Worked situation. A rule suggests shortening a warning sentence, but the shortened version removes the condition under which the warning applies. Test the operation on a copy or reviewable branch before applying an automatic change. Documentation should not turn a demonstration into an uncontrolled write.
Common mistake. Mechanical concision can erase logical scope, exceptions or uncertainty in high-stakes text. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Keep a separate semantic review for obligations, quantities, negations, exceptions and domain claims. Confirm that a copied command executes with the intended working directory and an appropriate non-destructive mode. An explanation is incomplete when its reproduction steps are unsafe.
Worked review: from a misleading report to a useful explanation
Consider a multilingual help center that publishes an English command reference and French and Arabic tutorials. The English `.vale.ini` applies an approved style to Markdown files. Before localizing the guide, the editor lists the actual `BasedOnStyles` selection and asks whether the same rules make sense in French and Arabic. The answer is not automatically yes: language-specific grammar and punctuation may require distinct scopes or rules, while brand names and CLI syntax remain shared.
The team first establishes a reproducible result on one English fixture. They note the tool version, configuration path, alert level and source span, then translate the explanation of that finding without modifying YAML keys. For French, they keep literal command names in code and select terminology from the current interface glossary. For Arabic, they isolate commands and test logical versus display order, especially around punctuation and interpolated paths.
A contributor proposes turning off the lint rule because a permitted product name is flagged. Instead the team checks whether a scoped vocabulary exception is suitable. They record the proper casing, an approved context and a counterexample where the generic form remains incorrect. After the change, both a valid product-name sentence and an intentionally invalid phrase are tested; merely obtaining a green CI job would not have shown whether the rule still worked.
The release note finally states exactly what was reviewed: the guide’s commands were preserved, style checks were performed on named locales, terminology was checked against the interface and meaning-sensitive instructions were read by people. It does not claim the entire translation is perfect or that Vale can validate factual equivalence. That measured statement gives future maintainers a trustworthy starting point.
Frequently asked questions
Does Vale translate my documents?
No. Vale checks prose against configured style rules. Translation, linguistic equivalence and subject-matter verification remain separate responsibilities. A well-configured linter can reveal inconsistent target-language terminology, but it cannot decide whether a paragraph accurately represents the source.
Should I translate `.vale.ini` or YAML rule keys?
No. Keep configuration syntax and literal values that Vale parses unchanged. Translate the explanatory text around them. A human-readable YAML `message` value may be localized if the style is intended for that language and its placeholders remain valid.
Why does one editor show alerts and another show none?
The installations may use different versions, configurations, working directories, extensions or input scopes. Reproduce the example on the command line, compare the policy and check whether the same document span was actually scanned.
Can a clean Vale result replace a professional reviewer?
No. Style checking offers consistency evidence, not proof of meaning, safety or domain accuracy. The higher the stakes of the content, the more valuable expert review of numerical values, negation, obligations and exceptions becomes.
How do I handle terms that are correct only in one locale?
Keep a documented locale-specific terminology policy. Test the accepted and rejected forms on representative text rather than forcing an English list across every language. Preserve interface names and code tokens separately.
What should go into a CI failure explanation?
Name the exact file or path, the rule, its intended policy, what changed and how to reproduce the diagnostic locally. Avoid saying that the translation itself failed if only a style threshold was violated.
A final quality checklist
- Confirm correct version, configuration path and selected styles.
- Preserve CLI commands, INI keys, YAML keys, filenames and product terms.
- Test a known match and non-match for important rules.
- Use locale-aware terminology, scope and Unicode test fixtures.
- Review semantic accuracy independently of prose-lint output.
- Provide reproducible remediation and an explicit exception record.