How can you translate textlint CLI tutorials and lint messages accurately when the underlying rules depend on a particular language, file format and configuration? This textlint CLI localization guide explains `.textlintrc`, pluggable rules and presets, Markdown and text processing, additional format plugins, formatters, `–fix`, `–dry-run`, glob patterns, CI output and Unicode QA. It serves documentation authors, translators, maintainers of open-source writing tools and global product teams.
textlint is a JavaScript-based, pluggable natural-language linter. It does not come with an all-knowing universal language policy: a project chooses specific rules, and some rules are written for Japanese, English or a domain’s prose conventions. A translated warning should therefore report what a configured rule detected, not declare every different linguistic construction incorrect. Translators must also separate explanatory language from executable commands, package names, configuration keys and diagnostic data.
Begin with a sample file, a pinned project dependency and the actual `.textlintrc` used by the repository. Keep command tokens such as `npx textlint`, flags, rule names, glob patterns and plugin identifiers literal. Translate surrounding explanations and useful rule messages while preserving variables, links and evidence. Run tests with accented words, East Asian punctuation, right-to-left scripts, Markdown code fences and filenames so the target-language instructions remain readable and reproducible.
Quick answers before you begin
- Install textlint and at least one rule before expecting useful findings.
- Read `.textlintrc` and determine the active rules, presets and plugins.
- Keep rule identifiers, package names, globs and CLI flags unchanged.
- Separate lint findings from actual mistranslations or factual problems.
- Test `–fix` using `–dry-run` or a reviewable copy before writing to files.
- Validate the selected output formatter and its consumers in CI.
This article is about textlint’s pluggable natural-language rule engine and the human interpretation of its messages. CSpell is a spelling dictionary checker; Vale enforces authored prose styles; markdownlint-cli2 checks Markdown structure. A good documentation workflow may combine them but should never describe their different findings as interchangeable.
A dependable starting sequence
Set up a small test repository with a Markdown page, a locally installed textlint package and a chosen example rule. Run `npx textlint –init` if the configuration does not exist, then `npx textlint README.md` after installing a rule. Keep the package manifest and the config alongside the source. A linter with no meaningful rules does not tell you that a manuscript is ready for publication.
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.
What textlint actually tests
textlint checks content against installed rules. Those rules can inspect prose patterns, punctuation, specific terms or document structure depending on their implementation; the engine alone cannot judge translation quality. 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. An English-language team installs textlint but no relevant rules, sees no errors, and assumes every localized tutorial has been certified. 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 quiet linter may indicate absent or disabled rules rather than excellent text. 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. Check the installed dependencies and introduce a known failing sentence for the intended rule. 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.
Use a local Node.js installation
Most projects run textlint from a local Node.js development dependency, often through `npx`, so contributors can reproduce a shared setup. 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 writer installs a global version and sees different rule-loading behavior from a teammate using the package lockfile. 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 local dependency and a global command may resolve different versions and plugins. 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 the installed package and version and run the command from the repository root. 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 `.textlintrc` carefully
textlint supports configuration files such as `.textlintrc.json` and related formats. The object names, booleans and rule identifiers are parsed by software and are not translatable prose. 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 rewrites `rules` and `plugins` into natural-language equivalents inside a JSON example for a Korean manual. 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 sample becomes invalid or misleading even if its surrounding paragraph is clear. 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 configuration keys literal and validate the parsed result with a simple known rule. 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.
Distinguish rules from the engine
An individual textlint rule describes a particular detectable condition; the engine is the runner that loads and executes it. Explain which one caused an alert. 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 tutorial attributes a publisher’s opinion about comma usage to textlint itself, although only a project-specific rule enforces it. 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. Stating a policy as universal discourages healthy locale-specific editorial decisions. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Name the installed rule and the project’s reason for enabling it. 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.
Install rules as dependencies
Rule packages commonly use names such as `textlint-rule-no-todo` and must be installed before configuration can use them. Package names remain literal identifiers. 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 translated installation guide replaces part of the package name with a synonym in another language, causing an install error. 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. A package manager cannot infer editorial intent from a translated name. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Copy package names directly from project dependencies and confirm resolution locally. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Interpret presets as collections
A preset groups rules and settings to make repeated configurations easier. Preset membership is not evidence that every rule suits every locale. 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 documentation team imports an English-oriented preset into a Japanese section and treats the new warnings as defects in Japanese grammar. 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. Presets can embody cultural and language assumptions that should be reviewed, not inherited blindly. 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. List the enabled constituent rules and test a representative example in the target language. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Read rule options semantically
Rule options can include thresholds or lists of forbidden expressions. Their structure is configuration, but the policy’s meaning needs explanation. 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 changes a limit and describes the result as ‘more accurate’, although the actual difference is that the rule flags fewer sentences. 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. Threshold changes alter sensitivity, not necessarily correctness. 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 the exact configuration and illustrate both an accepted and rejected example. 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.
Disable rules narrowly
Setting a rule to false removes that check for the configured scope. Teams should distinguish a justified exception from convenient suppression. 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. One false positive on a medical term leads a maintainer to disable the entire spell-related preset. 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 blanket suppression may hide future genuine errors in unrelated documents. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Keep a counterexample and choose a scoped adjustment when possible. 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.
Treat plugin names as syntax
Plugins extend the formats or processing that textlint can handle. The plugin identifier and installation instructions belong to software configuration. 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 localized help page renames `html` plugin configuration to its target-language noun, leaving HTML files unprocessed. 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 successful Markdown run does not prove the HTML plugin ran. 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. Include a tiny HTML fixture and confirm an installed plugin is actually used. 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.
Check default Markdown and text inputs
Markdown and plain text are supported by default. A working file glob determines which specific documents are examined. 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 team assumes exported DOCX files were scanned because a `docs/` command completed, but only supported source formats were processed. 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. Directory inclusion does not imply every binary or generated format is understood. 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. List the resolved input files and keep a separate review for unsupported formats. 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.
Quote glob patterns faithfully
Glob patterns may match directory trees and extensions, and quoting them avoids shell-dependent expansion. They are executable selectors, not editorial descriptions. 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 tutorial translates the asterisks away from `docs/**/*.md`, making its copyable example check almost nothing. 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. Different shells can expand a pattern before textlint receives it, obscuring which files were intended. 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. Use the command exactly as documented, test matching files and inspect the result. 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.
Use `.textlintignore` deliberately
Ignore patterns can exclude generated content, dependencies or other intentional non-targets. Exclusion is a scope decision, not proof that files are correct. 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 project ignores all `docs/` to make CI green, then advertises a documentation quality gate. 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. The resulting report says nothing about the excluded documentation. 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 short inventory of exclusions and explain why each one exists. 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.
Understand formatting and line offsets
A diagnostic relates a rule to a source file and location. Formatting output changes how a tool displays evidence without changing the underlying rule finding. 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 report translated into prose loses the filename and line number; a teammate cannot locate the detected sentence. 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. Human paraphrase is not a replacement for machine-readable diagnostic fields. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Preserve paths and offsets and add a clear sentence explaining what the rule checks. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Choose the right output formatter
The CLI supports formatters for different readers and CI consumers, including human-friendly and structured formats. A JSON report should remain valid JSON. 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 editor translates machine-readable JSON property names in a report attached to a build job, breaking its parser. 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. Output presentation and data schema must be distinguished carefully. 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. Pass `–format` with a supported value and parse the output with the intended consumer. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Explain `–quiet` without overclaiming
A quiet option can reduce reported noise, often to errors, depending on the selected output behavior. It does not repair the underlying text. 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 release manager interprets quieter output as evidence that spelling and style improved overnight. 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. Changing what is displayed is not the same as changing the document. 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. Compare normal and quiet runs on the same deliberately flawed fixture. 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.
Use `–fix` with change review
Some rules support automatic fixes, and `–fix` can apply supported edits. The CLI cannot safely infer every translator’s intended meaning. 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 team runs fixes across a multilingual corpus and accepts substitutions that changed quoted interface labels. 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. An automatic suggestion can be syntactically neat but semantically wrong. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Run a dry run when available, review diffs and preserve source files before applying edits. 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.
Differentiate `–dry-run` and editing
The `–dry-run` option is designed to show fixing behavior without changing files, when used with the relevant fix workflow. Its promise must be described precisely. 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 translated tutorial describes dry run as ‘testing every possible solution’ rather than simulating available configured fixes. 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 dry run is not a semantic validator or proof that an edit would be desirable. 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. Use a disposable fixture and compare filesystem content before and after dry-run execution. 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.
Protect code fences and inline syntax
Markdown content combines prose with literal identifiers and code blocks. A rule or parser may handle those elements differently, so examples need 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. A replacement rule modifies a sample REST header inside a code span while the explanatory paragraph is left unchanged. 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. Breaking copyable source text creates a documentation defect even if the prose reads better. 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. Keep protected terms in fixtures and compare rendered code character for character. 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.
Review rule suppression comments
Filter rules may allow localized suppression in selected text regions, such as recognized comments. Such markers are configuration-like syntax. 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 rewrites a disable marker to ordinary language, causing the supposedly ignored section to trigger the original rule. 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 hidden suppression may be mistaken for evidence that a term passed validation. 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. Preserve comment syntax and document the exact scope and rationale of each suppression. 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.
Capture structured CI reports
A CI job needs consistent inputs, pinned dependencies and output formats that reviewers can inspect. Reports can be archived without converting them into informal summaries. 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 pipeline uses a human-colored console formatter and attempts to parse it as JSON when creating annotations. 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 successful command invocation is different from a functioning report consumer. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Test the full workflow with one intentional rule violation and verify the resulting annotation. 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.
Use the cache without misleading readers
Caching can avoid rechecking unchanged files and speed routine documentation jobs. Its results still depend on the correctness of the configured inputs and cache strategy. 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 maintainer changes a rule but expects all historic files to be re-evaluated without considering cached results. 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. Stale cached outputs can confuse diagnosis of a newly revised language policy. Green automation status is not an editorial approval stamp. Human review remains necessary for dangerous ambiguity, meaning shifts and context-specific terminology.
Practical check. Force an appropriate fresh check when rules, dependencies or the intended input corpus change. Compare results on the intended locale and a contrasting locale where appropriate. Differences can be expected, but each difference should have a policy reason.
Review Unicode punctuation
Different languages use different quotation marks, commas, sentence terminators and spacing. A rule written for ASCII punctuation may not generalize. 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 punctuation rule warns on every Japanese full stop even though the sentence is normal Japanese text. 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 linter’s token boundary is a technical implementation detail, not the full linguistic standard. 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. Test representative locale punctuation and document known limitations before enforcing the rule. Inspect filenames, URLs, line positions and encodings after export. Visual reading alone can miss subtle Unicode or escaping damage.
Check decomposed accented characters
Accented characters may be represented in composed or decomposed Unicode forms. The same visible word can behave differently under some rule implementations. 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 French word passes one regex but fails after copy-paste from a different editor because its accent is represented differently. 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. Visual inspection cannot identify all code-point differences. 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. Compare NFC and NFD fixtures and verify whether normalization is required in the chosen workflow. 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.
Handle right-to-left scripts
Arabic and Hebrew often place LTR commands, file paths and numbers inside RTL sentences. Preserve logical text order and make examples easy to copy. 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 guide visually reverses a shell option inside an Arabic paragraph, and readers copy a broken command. 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 typographically appealing layout can conceal changed underlying characters. Prevent accidental promises. Words such as ‘fixed’, ‘secure’, ‘complete’ and ‘approved’ can overstate what a style checker has established.
Practical check. Inspect code points and run copied terminal examples rather than relying only on screenshots. 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.
Separate warnings from translations
A warning from a rule is a hypothesis about configured policy, not an independent translator’s verdict. Reviewer notes should specify the real source and target 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 translated FAQ says ‘the Japanese sentence is wrong’ solely because an English punctuation rule fired. 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. Users may treat tool limitations as a condemnation of valid target-language text. 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. Explain the exact rule, its intended language and one example where human judgment overrides 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.
Design a glossary handoff
Package names, CLI flags, rule identifiers, preferred terms and editor-facing messages belong in separate glossary columns. Their treatment is not identical. 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 contractor localizes all words in a sample command but leaves English UI terms in a step-by-step guide where the interface is actually localized. 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. Blanket translate-or-preserve rules lose essential context. 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 approved target labels for user-facing UI and literal preservation rules for executable tokens. 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.
Troubleshoot contradictory results
When local and CI findings differ, compare Node.js versions, lockfiles, config search paths, input selection and plugin installation. The problem may not be linguistic. 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 developer sees a warning in CI that another contributor cannot reproduce because one machine loads a different preset version. 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. Assigning blame to the text rather than the environment delays resolution. 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. Re-run on the same lockfile and report the exact command and resolved configuration. 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 changes
Textlint can help with mechanical style, but it cannot prove that a safety warning, legal condition or medical sentence retained the original meaning. 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 fix shortens a cautionary sentence by removing ‘unless authorized’; lint no longer complains, yet the instruction becomes unsafe. 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. Fluent output can hide a changed obligation or exception. A copied example can fail when punctuation, spaces or capitalization change. Do not localize literal syntax merely because it resembles English prose.
Practical check. Review negations, numerical ranges, permissions and conditional statements with a qualified human. 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
Imagine a global developer-docs repository with an English onboarding guide, Japanese workflow notes and Arabic troubleshooting pages. The English section uses a punctuation and clarity preset. The team records which rules are installed instead of assuming that all language variants share them. A `docs/**/*.md` run is checked for scope; otherwise a promising green result might mean whole directories were silently absent.
The translator then separates literal content into commands, flags, JSON keys, rule names and file patterns. Only explanatory prose receives ordinary translation. The Japanese documentation uses its own editorial guidelines and reviewed rules. A case-sensitive CLI token stays unchanged even when neighboring words and punctuation change. Before any autofix, the team runs `–dry-run` on a small test fixture and inspects the proposed result.
For CI, a machine-readable formatter is chosen when another program must consume the findings. The team confirms that the formatter output can actually be parsed; it never translates JSON field names. The documentation also explains what a rule can detect and what it cannot. One example that should fail and one that should pass are preserved as regressions whenever policy changes.
Finally, a reviewer checks meaning-sensitive sentences, especially restrictions, permissions, measurements and safety instructions. The result is a useful handoff: the source, target, exact rule, approved exception and reproduction command. The team can truthfully say which files underwent which checks, rather than promising that every translation was proved correct by automated linting.
Frequently asked questions
Does textlint work without additional rules?
The engine needs meaningful configured checks to produce useful style findings. Install suitable rule packages or presets and verify the intended rule loads with a known test phrase. A quiet run alone does not establish quality.
Is textlint a translation engine or grammar checker for every language?
No. It is a pluggable linting framework for natural-language content. Actual behavior depends on the rules, their language assumptions and supported formats; human translation review is still necessary.
What is the difference between a rule and a preset?
A rule checks a particular condition. A preset packages a collection of rules and settings. Review the content of any preset before using it as a mandatory gate for a different language or documentation domain.
When should I use `–fix`?
Use automatic fixing when the relevant rule supports it, the change is safe and you can inspect the diff. Dry-run and a reviewable branch are appropriate precautions. Do not assume a mechanical edit preserves legal or technical meaning.
Why did textlint ignore my file?
The file may not match the requested path or glob, may be excluded by ignore settings, may require a format plugin or may be outside the current directory. Check input selection before changing the text itself.
Can I translate machine-readable formatter output?
Translate human explanations, not JSON keys, control fields or identifiers consumed by another tool. Preserve structured output and localize it only at a presentation layer designed for that purpose.
A final quality checklist
- Verify the installed textlint version, rule packages and loaded config.
- Keep executable flags, package names, globs and JSON keys literal.
- Prove that the selected rule catches a known fixture.
- Review every automatic fix, especially in multilingual and high-stakes text.
- Test formatter output with its actual parser or CI consumer.
- Maintain locale-specific terminology and a human semantic review.