How do you translate commitlint CLI documentation, Conventional Commit error messages and Git-hook instructions without breaking the rules that release automation depends on? This world-facing guide explains commitlint configuration, commit-message parsing, rule severity, CI commit ranges, terminal output and Unicode quality assurance for technical writers, software localization teams and maintainers. It addresses searches such as how to localize commitlint errors, translate conventional commit messages and document commitlint CI checks correctly.
commitlint checks commit messages against configured rules; it is not a natural-language translator, release publisher or universal judge of writing quality. A parser may depend on the exact spelling of a type such as feat or fix, the position of a colon, or a configured scope. Those symbols are data for a tool, while explanations, examples and contributor instructions can be written in a reader’s language. Confusing the layers can make a guide sound fluent but turn a working repository workflow into one that rejects legitimate commits.
The practical answer is to keep executable syntax and repository conventions stable, explain the meaning of each diagnostic clearly, test real inputs with the exact configuration used by the project, and review how results appear in hooks and CI. This guide begins with a quick checklist, then moves from simple commit examples to configuration, multilingual teams, failed pipelines, accessibility, troubleshooting, detailed editing cases and frequently asked questions.
Quick answer: a working localization checklist
- Preserve executable flags, rule keys, Git references, type prefixes and file paths exactly.
- Name the installed version and resolved rules rather than assuming defaults.
- Separate stored commit messages from translated release-note prose.
- Demonstrate one pass, one parse failure, one rule failure and one CI range failure.
- Check Unicode, bidirectional rendering, smart punctuation and copy-paste fidelity.
- Explain how to repair errors without casually rewriting shared Git history.
- Review diagnostics for accessibility, actionability and accurate severity.
- Link to the maintained reference and revalidate examples when config changes.
What commitlint is actually checking
Git records a commit message as part of a change, and downstream tools may inspect that message to categorize what happened. commitlint provides a programmable check against a repository’s agreed message conventions. The check may run locally when a developer writes a message, or later in CI on one or several commits. A failure means a rule did not pass; it does not necessarily mean the underlying code is defective. A translated contributor guide must preserve that difference. Saying a commit failed to build when only its message failed linting sends a new contributor to the wrong place.
Conventional Commits provides a common format, often expressed as type, optional scope, colon and subject. For example, feat(auth): add a recovery link is a plausible structured message. The developer decides whether the code change warrants that type; commitlint tests the form under an installed configuration. The protocol-like part is distinct from the ordinary sentence after the colon. Editors should label demonstrations as examples, not imply that every repository enables every conventional rule.
Before translating a message or diagram, identify the system being documented: which commitlint version is installed, which config is loaded, which parser preset is active and which trigger runs the check. A project may allow localized subject descriptions while reserving English type prefixes. Another may enforce a restricted character set in certain fields. If the writer assumes a global policy, readers inherit a false rule. The strongest localization is faithful to the actual executable policy and still understandable to someone encountering Git for the first time.
Quick start that separates commands from language
An isolated teaching example can pipe a test message into commitlint: echo ‘feat: add search filters’ | npx commitlint –default-config. The official CLI describes –default-config as a fallback when no rules are found. In a repository with its own rules, use the repository’s resolved configuration rather than assuming the fallback. Never translate npx, commitlint, the flag spelling, the pipe symbol or the type marker inside a runnable example unless the configured parser explicitly supports a different marker.
The human explanation can be localized completely: this command reads a test message from standard input and reports whether it meets the selected rules. Explain standard input as text passed into a program, not as a particular keyboard key. Show a passing and failing case under identical settings, then invite the reader to change one variable. A subject without a separating colon may fail for a different reason from a subject that violates maximum length. The output should be taught as evidence, not a magic verdict.
When publishing examples on the web, keep code blocks copyable and preserve straight ASCII punctuation where syntax requires it. Curly quotation marks inserted by a content editor may change the shell command. If a translated code sample uses a typographic dash in –from, the reader may see a cryptic error unrelated to the described rule. A good guide distinguishes display typography from characters the shell or parser interprets. Test commands copied from the final rendered page, not merely the original draft.
The boundary between translatable and non-translatable strings
Treat the commitlint executable name, flags, file names, rule identifiers, Git references, placeholder variables and declared type tokens as stable identifiers. Explain them in prose rather than renaming them inside machine-facing examples. The sentence displayed to a contributor, by contrast, is a suitable localization target if the project controls the message catalog or surrounding documentation. A rule ID such as type-enum should be retained so the reader can match it to a log line or configuration entry. Its explanation can say that the type must be drawn from an approved list.
Commit subjects deserve a more careful decision. A subject is ordinary language, but it also forms part of immutable repository history once committed. Translating it for a release note is different from editing the stored message. Many release pipelines derive changelogs and semantic versioning decisions from types and breaking-change markers. If a translation changes the meaning from a fix to a feature, it may introduce an incorrect release promise. Where the literal subject is quoted as evidence, retain the source and place the translation nearby.
Think of three layers: the source-control record, the parser and configuration, and the reader-facing teaching material. The first two require functional equivalence; the third requires clear meaning and appropriate register. An experienced editor annotates examples to state which layer is being shown. This small habit prevents a surprising number of failures when localized documentation is copied into team templates, onboarding messages or repository issue discussions.
Conventional Commit anatomy for international readers
An ordinary conventional header starts with a type such as feat, fix, docs or chore, optionally followed by a scope in parentheses, and then a colon, space and short subject. The set of allowed types is not universal; projects can select rules and parser presets. In explanatory translation, type is best described as the category of change, scope as the affected area, and subject as the concise description. Do not suggest that scope is a permission boundary, a Git branch or a file path. Sometimes it corresponds to a package or feature, but that is a team convention.
A breaking change may be indicated through an exclamation mark in the header or a footer recognized by the chosen conventions. This metadata affects how release automation may interpret the commit. A translator must never weaken breaking to notable, unusual or important without retaining the compatibility meaning. An important user-interface change may not be breaking; a small-looking API change can be. Explain what consumers must alter when possible, and refer technical judgment to maintainers rather than inferring it from prose alone.
For multilingual examples, compare feat(ui): improve keyboard navigation with a subject written in another language while keeping feat(ui): stable. Whether a non-English subject passes depends on active rules, not on commitlint inherently requiring English. Demonstrate the observed result in the project environment. This is educationally stronger than stating either that all languages are supported without limits or that Conventional Commits requires English text. It separates the protocol from the human expression.
Configuration files are code, not prose to rewrite
Commitlint configuration can live in recognized JavaScript, JSON or other supported formats depending on the installed version and loaders. A common pattern extends @commitlint/config-conventional and adds rule overrides. An editor translating the accompanying tutorial should preserve import paths, module names, property keys, quoting and nesting. Changing the key extends into a translated synonym will not produce a friendlier program; it will alter or invalidate configuration. The correct localization is a nearby explanation of what the key does.
Rule settings commonly use a level, an applicability value and an expected value. Official guidance describes levels 0 for off, 1 for warning and 2 for error, and uses always or never for the relationship. This is not a ranking of how important the message sounds in natural language. Translating warning as suggestion while still describing it as blocking may create an inconsistency. Always inspect the project’s CI policy, because a pipeline can decide what to do with a nonzero lint result separately from the text of a diagnostic.
Shareable configuration packages and parser presets are names in a dependency ecosystem. Write their exact package identifiers, including punctuation and capitalization, and link to documentation. When a team wants friendlier native-language rule descriptions, add a glossary: type-enum means only approved types, subject-empty means the subject must be present, header-max-length concerns the header’s size. The glossary translates a concept while leaving the machine key searchable.
Severity, applicability and the meaning of failure
Suppose a configuration contains header-max-length: [2, ‘always’, 72]. The meaning is an error-level check requiring the header not to exceed the configured maximum under that rule. Do not translate this as a recommendation that all commit messages should be precisely 72 words; it concerns length as evaluated by the rule and uses a numerical threshold. If another repository turns the same check off, its behavior changes. This is why examples must name the active configuration, not present one set of thresholds as law.
A diagnostic display often carries multiple pieces of meaning: which rule failed, which value was observed, the expected relationship and the result code. Preserve that structure in a translated explanation. A terminal may color failures red, but color alone should not be the only indicator in accessible documentation. State in words what the contributor can change and whether the action is safe. For example, shortening a subject is usually editorial; changing a type marker may alter downstream release categorization and merits checking the actual code change.
Do not conflate a parser error with a style disagreement. An empty subject, an unrecognized type and a malformed footer may come from different rule checks or parsing stages. Translate the actual cause; avoid generic phrases such as incorrect commit. A reader can act on a precise explanation. In teaching materials, pair each symptom with the smallest edit that fixes it, then note the reason it matters. This turns a linting guide into a tool for learning conventions rather than merely passing checks.
Git hooks and the message a contributor sees
A commit-msg hook can examine a message before Git completes a commit, which is useful because feedback arrives while the message is still easy to revise. The hook may invoke npx commitlint –edit, which reads a commit message file. Do not describe it as validating staged code or running the entire test suite unless the hook actually does those things. A different hook, such as pre-commit, is often associated with files being staged; mixing the two in a translated guide misleads people about the timing and purpose of validation.
Hook managers differ in how they install and invoke scripts. Some projects use Husky, others use different tooling or direct Git hooks. Your tutorial should name its specific setup and avoid suggesting one installation command is permanent across releases. The path .git/hooks and the commit message file have operational meanings. Translate directory descriptions but not actual path characters. If documentation targets Windows, macOS and Linux, explain that shell quoting and environment behavior can vary. Do not promise a command works identically on all shells without testing.
A good localized failure message tells contributors what happened, where to look, and what to do next: the commit header was rejected by type-enum; consult the repository’s allowed types; change only the header if its meaning was inaccurate; retry the commit. This is more humane than an alarming, generic fatal error. Avoid blaming non-native English speakers for a format error. The repository may accept any language for the subject even while reserving a short, parseable set of type codes.
CI validation of commit ranges
Teams often lint a range of commits in continuous integration so a clean local hook is not the only line of defense. The official CLI exposes –from and –to to delimit the range, –from-last-tag for one form of lower bound and –last to inspect a single recent commit. These flags must not be translated or silently swapped. A range should be chosen for the event being validated: a pull request, a release candidate or a new set of commits on the default branch. The best reference point can differ between workflows.
Documentation should explain that Git references are relative to the repository state available inside the runner. A shallow checkout can omit earlier commits or tags, causing a command to fail or see an unexpected history. A localization guide that blames the contributor’s grammar for a missing Git range is diagnosing the wrong subsystem. Show how to inspect the checkout and ref calculation before evaluating the reported lint rule. Distinguish a failed tool invocation from a successful invocation that found an invalid commit message.
For international contributors, translate CI status labels consistently: pending means the job has not finished; failed means a check reported failure; skipped means it was not executed under the condition. A commitlint job may be one requirement among several in a protected-branch policy. If the page describes it as the sole release gate, readers may draw incorrect conclusions about merge safety. A precise explanation keeps the technical scope narrow and the repair instructions actionable.
Scopes, packages and names that must remain identifiable
Scopes can be names such as api, auth, cli or docs, but they may also reflect package boundaries in a monorepo. When a scope appears in a rule-enforced enumeration, altering its spelling in translation can trigger a lint failure. Preserve the identifier inside working headers and describe the component outside the code. If the documented team changed a package name, make clear whether the old scope is still valid for historical commits or newly prohibited for future ones. Repository history cannot be assumed to follow current naming.
A localizer may be tempted to translate ui to the equivalent abbreviation in a target language. That is safe in explanation but not necessarily in a commit header. The reader needs to understand why a seemingly arbitrary English token remains in a Spanish, Arabic or Japanese tutorial. It is a shared code in a documented convention, not a claim that software engineering should take place in only one language. By explaining this distinction, the article avoids both technical errors and unnecessary cultural assumptions.
Packages and scopes are not interchangeable in every project. Some teams use a broad feature name, others use a directory, and many permit no scope at all. Document the active allowed list, whether scopes are required and what to do when a change spans components. Avoid manufacturing a universal convention. If no accurate scope exists, the best action is to ask a maintainer to clarify the policy rather than inventing a new token that passes only in a localized example.
Unicode, length rules and character counting
Commit subjects may contain accented letters, non-Latin scripts, combining marks and emoji. These are valid forms of human expression in many environments, but length checks, terminal rendering and downstream changelog tools may treat them differently. Distinguish a character visible to a human from a Unicode code point and from an encoded byte. Do not assert that an 80-character limit is necessarily an 80-byte limit. To write trustworthy guidance, run representative multilingual messages through the actual installed parser and capture the result.
Unicode normalization also matters when superficially identical strings have different representations. A composed accented character and a base character plus combining mark may look the same but compare differently in some contexts. Commitlint’s active rules, regular expressions and surrounding tooling determine the observed behavior. A guide should not promise perfect linguistic awareness from a generic length rule. It should say how the team tests its chosen limits and how it handles edge cases without punishing readable, meaningful messages.
Bidirectional scripts require extra care in documentation. Mixed Arabic or Hebrew subjects, Latin type tokens, punctuation and version-like identifiers can appear in surprising visual order. Preserve the underlying source text in copyable code blocks and use direction-aware markup or a clear label when rendering examples. Do not add invisible direction controls inside machine-facing strings casually. If a contributor copies an example, they should get the intended bytes, not a visually reassuring but functionally different artifact.
Terminal output, color and localization accessibility
Commitlint can present terse reports with rule names, counts and help information. A documentation writer can translate the explanation around a captured terminal transcript, but a translated screenshot should not pretend to be genuine output from an unmodified upstream CLI. Label any illustrative or simulated output plainly. When translating a user’s troubleshooting steps, identify whether the reporter must supply the command, the installed version, the config location or the failure log. This removes unnecessary back-and-forth.
Terminal colors, line wrapping and monospace alignment vary by locale and font. A screenshot readable in English may cut off a translated explanation or obscure the rule identifier in a narrow mobile viewport. Provide selectable text where possible and use a caption that carries the same key information. A red cross without a written description is not accessible to every reader. A CLI localization article should work for someone using a screen reader, a low-bandwidth connection or a text-only environment.
Errors should be translated with consistent verbs. Failed, rejected, skipped, ignored and warned represent different states. Don’t turn a warning into an instruction to rewrite history, and don’t suggest force-pushing as a routine response to a message style check. If a malformed commit has already been shared, changing it may affect collaboration. The documentation should distinguish editing a new local message from rewriting published history, which requires repository-specific care and coordination.
Using translations without changing Git history
Many teams want localized release notes or changelogs but keep Git history in one shared format. Those needs are compatible. Keep the original commit identifiers and machine-readable markers stable; generate a reader-facing release note that explains the change in the audience’s language. If a term has a specialized meaning, use an agreed glossary. Fix denotes a bug repair rather than every minor edit, and feat denotes a feature category rather than proof that a feature is complete in every environment.
Never silently reinterpret a breaking-change marker merely to produce a friendlier title. A release note can soften the tone while preserving the substance: this release requires applications to update the authentication endpoint. It cannot soften the actual compatibility requirement. If the message lacks enough detail to support a translation, obtain maintainer clarification. Translation accuracy sometimes depends on evidence outside the source sentence, such as migration instructions, feature flags and API documentation.
Preserve attribution and chronology. Two commits may share a similar subject while affecting different packages or versions. Combining them into one localized item may hide a security fix or double-count a feature. Readers need to know what changed in the version they use. The lint policy helps maintain structured inputs, but it cannot guarantee that a release note is complete or accurate. Maintain an editorial review after the automated step.
Security, privacy and example hygiene
Commit subjects are often copied into public release announcements, issue trackers or build logs. A localization guide must avoid normalizing the inclusion of tokens, private customer names, internal server addresses or sensitive incident details in examples. A commit type is not a security classification. A subject like fix: rotate exposed production key should be reviewed before publishing its surrounding context. Translating a secret does not make it safe to reveal.
Use synthetic data for tutorials. If demonstrating a failing commit, invent a generic feature area and an imaginary issue identifier, and say that the data is illustrative. If readers need to reproduce a bug, provide the smallest safe input rather than copying internal messages. A maintainer should check whether generated release notes expose commit bodies or footers beyond the intended audience. Some pipelines automatically publish those fields; localization may amplify visibility even though it changes no permissions.
Security reviews also apply to sample scripts. Avoid telling users to bypass hooks with no verification, disable all lint rules or remove branch protections just to pass a localized example. Explain how to inspect a misconfigured rule and propose an intentional policy update through review. A translation should help people do the right thing within the tool’s constraints, rather than offering a shortcut that defeats the team’s established controls.
Writing clear multilingual contributor instructions
Strong contributor documentation begins with a task: write a short structured message, run a check, read a diagnostic and make a justified correction. Put those actions before a long history of conventional commit conventions. Give readers a concise example they can imitate, followed by the reason each part is present. If the project requires specific types or scopes, link the current list. If a literal English token must remain unchanged, explain that requirement directly, rather than leaving a reader to guess which words are safe to translate.
Use stable terminology throughout the article. Prefer one target-language equivalent for commit, commit message, header, subject, scope, rule and hook, then acknowledge regional variants where useful. Do not let scope alternate among feature, module, namespace and package without explanation. In multilingual teams, create a compact bilingual glossary with preserved technical identifiers. The aim is not to erase familiar English engineering words but to prevent misunderstandings about responsibility and behavior.
Add practical context to messages: show a rule violation, its diagnosis, the smallest change, and what must not be changed. Invite the reader to test on a disposable branch rather than immediately rewriting shared history. Separate examples for first-time contributors, maintainers who edit configuration, and translators who update documents. Their permissions and tasks differ. A guide that tells every reader to edit the repository’s lint config is neither safe nor useful.
Testing a translated guide, not just the source project
An editor should test the exact command and sample message displayed in the final published language. Copy from the rendered page into a clean terminal or documented test environment, then compare the result with the promised output. Check that code formatting has not converted hyphens, quotes or colons. If using a sandbox repository, record the installed version and resolved configuration. A passing result under a fallback config does not prove a command will pass in the production repository’s stricter policy.
Review at least three outcomes: a passing commit, a malformed header and a message rejected by a configured rule. Add a Unicode case and a very long header. If CI is involved, include a valid and invalid commit range and verify the runner actually has the necessary Git history. Documentation should distinguish absence of data from validation failure. Testing one happy path is insufficient for an international audience that will encounter varied shells, character sets and automation conditions.
Finally, ask a technical reviewer who did not write the translation to follow the steps. Do they understand which text can be localized? Can they identify why the check failed without reading the English original? Do links lead to maintained documentation? Is the output accessible without relying on colors? Address those observations before publication. The quality standard is not a word-for-word resemblance; it is reproducible, accurate guidance that helps the reader act confidently.
A realistic workflow from incoming message to approved documentation
Imagine a repository that uses a commit-msg hook locally and a CI job on pull requests. A contributor submits an authentication fix with an unrecognized type marker. The hook reports type-enum. First confirm that the actual change is a bug fix and not a feature. Then revise the uncommitted message to use the approved fix marker while keeping the subject accurate. Do not assume the localizer’s task is to change the project’s type list. If the subject is in another language and the project permits that, it may remain as written.
The documentation editor now prepares a localized help page. The page quotes the failing marker as evidence, describes the allowed list, and demonstrates a passing example under the real config. It states that a commit already pushed to a shared branch should not be rewritten casually. The editor also makes an accessible transcript of the CI failure and verifies that the range check selects the relevant commits. The final explanation is concise at the top, with more detailed rationale below.
Later, the release team generates user-facing notes from the Git history. The notes may be translated and polished, but the message classification and release scope are checked against the code and release artifacts. This end-to-end workflow shows why localization is not merely translating an error sentence. It preserves a traceable chain from developer intention to parser result to release communication, each with different acceptable edits.
When a rule appears culturally or linguistically unfair
A rule restricting a type token to a fixed English list is usually a protocol choice, not necessarily a judgment about which language contributors may use. The body or subject may remain multilingual. But some teams also impose rules such as sentence case, maximum length or restricted characters that can have uneven effects across languages. The correct response is to test real examples and discuss whether the policy meets its functional objective. Do not promise inclusion while leaving a regex that excludes the audience’s script.
Document policy options without making changes on a reader’s behalf. A team might allow multilingual subjects, relax a style check, reserve ASCII only for types and scopes, or define clear transliteration rules for identifiers. Each choice has maintenance costs, including searchability, automation compatibility and review consistency. A translator can facilitate the conversation by showing concrete examples and their observed results. The maintainers must approve any change that affects the repository’s parser or release process.
The point is fairness through clarity and evidence. Contributors should know which constraints are necessary for automation and which are habits that can be reconsidered. Readers should not have to interpret a short lint error as a statement about their linguistic competence. A respectful, precise guide can help a team keep machine-readable conventions and welcome contributors who write in different languages.
What commitlint cannot decide for you
commitlint can enforce syntax and configured patterns, but it cannot independently verify that a commit labeled fix actually repairs a defect, that a change is backward compatible or that a message is truthful. A passing status therefore does not mean the release classification is substantively correct. The engineer and reviewer still need to inspect the code and user impact. Translation should preserve this limitation. Don’t write that the tool guarantees semantic versioning or automatically releases the package when only commit validation has run.
The same applies to grammar and tone. A message may fit a short format yet be unhelpful to a user: fix: thing. An editorial policy can encourage concrete subjects, but a length rule alone cannot supply missing context. A useful guide shows why improve retry handling for failed requests is clearer than fix issue, while noting that both can still require domain review. The aim is intelligible change history, not merely an absence of red diagnostic lines.
Tool versions and configurations evolve. Check the CLI’s current help when writing a release-specific tutorial, and use the version actually installed in the repository for definitive behavior. Avoid hard-coding claims about all releases forever. Linking to the maintained CLI reference helps the reader resolve differences and reduces the chance of an outdated translated tutorial becoming a source of new errors.
Editorial style for translated error explanations
A strong explanation uses ordinary language before jargon: your commit type is not on this project’s approved list. Then it names the stable rule identifier: type-enum. Then it offers the repair: consult the list, choose the type that truly describes the change, and rerun the check. This structure serves expert maintainers and newer contributors. The exact machine name is available for searching logs, while the accompanying language makes it useful.
Prefer action-oriented phrases over metaphor. A malformed footer is not a broken promise, and a missing scope is not necessarily an authorization failure. Avoid translating Git ref as document reference if that expression is more commonly used for bibliographies in the target language. Provide a short parenthetical explanation such as a branch, tag or commit identifier. Test unfamiliar terminology with an experienced target-language engineer to avoid translations that read naturally but identify the wrong object.
In terminal examples, keep line breaks and indentation meaningful. If a localization system injects labels, verify they do not merge with a rule name or obscure the original failing message. When translating a screenshot caption, include the rule and next action so a screen-reader user does not need the image. Good diagnostics are small teaching moments: a problem, a cause and a safe fix, all grounded in observable behavior.
Migration between team conventions
Suppose an organization changes from a loose commit style to a strict Conventional Commit policy. New contributors may encounter old history that does not conform. A translated guide must explain whether checks apply to the latest commit, the pull-request range or all reachable history. Do not tell readers to rewrite hundreds of old commits because a current rule would reject them. The team should decide an explicit migration boundary and configure its CI accordingly. A localized document can explain the boundary without secretly altering it.
During migration, maintain a map from old terminology to new tokens, and distinguish deprecated labels from currently allowed ones. A localized glossary can help contributors who learned an earlier workflow. Show which examples represent historical data and which are recommended for new messages. The tutorial should name the exact repo policy rather than generalizing from a sample file. Contributors will trust the documentation only if the commands correspond to what the repository currently runs.
Be cautious with automatic message generators. They may suggest a type that passes lint while misrepresenting the change. Review the diff and choose the category deliberately. When an automated tool produces a translated header, verify its delimiters and Unicode handling. Human review remains essential where release automation infers version impact from commit metadata.
Maintenance, ownership and a useful review cadence
Every public guide needs a clear owner and a way to detect when it is stale. A commitlint release may change supported flags, defaults or error presentation; a repository may change its config without upgrading the executable. Check both. Record the reviewed command and installation context in maintainers’ notes, while keeping the reader-facing page focused on action. For world-facing writing, avoid assuming a single package manager, operating system or time zone. State alternatives where they affect reproducibility.
Review localization after changes to the conventional type list, parser preset, hook manager, CI checkout strategy and release note generator. Each of these can alter an example’s real-world result. A translated page should not be a frozen snapshot that keeps instructing contributors to run obsolete commands. The easiest maintenance habit is to preserve a small bank of test messages and revalidate them when tool or policy changes. Include one right-to-left and one combining-character case if your audience uses those scripts.
Invite corrections through a safe channel, ideally with the exact page section and minimal repro command. Keep security-sensitive logs redacted. Distinguish an editorial terminology correction from a machine-rule change; the former can often ship quickly, the latter needs normal repository review. A trustworthy educational article evolves with evidence while retaining a stable explanation of the underlying concepts.
Twelve practical translation and debugging cases
Case: translated type token
A Portuguese contributor writes a localized equivalent of feat at the start of a commit and receives type-enum. Explain that the project’s parser expects the configured token and that only the subject is free text unless the rules say otherwise. Show the unchanged token beside a Portuguese subject. Never claim the natural language is forbidden merely because a parser-facing field uses a fixed vocabulary.
Case: missing separator
A new developer writes fix(auth) improve session renewal. The intended category is apparent to a human, but the documented format expects a colon after the header. Correct the delimiter in the example and explain why tokenization matters. Do not replace the whole subject with an unrelated canned sentence; the point of the lesson is punctuation in a structured record.
Case: misleading fix
A pull request changes a public API behavior but is labeled fix because the subject sounds modest. The linter may pass. Editorial review must still determine whether this affects compatibility and release classification. Explain the difference between syntax validation and semantic judgment, and ask maintainers to provide a migration statement if consumers must adapt. A localized announcement should never promise no breaking changes solely because commitlint succeeded.
Case: narrow CI checkout
A pull-request job invokes commitlint with –from and –to, but the lower reference is absent in the checkout. The command fails before validating a useful range. Translate the log’s missing-reference diagnosis faithfully, then explain where Git checkout depth or fetching may need review. Do not instruct contributors to shorten commit subjects as a response to a missing history object.
Case: shared history rewritten
A team member has already pushed a message with an imperfect subject. A translated guide recommends amending and force-pushing as if it were always safe. Replace that instruction with a warning about shared history and repository policy. The problem is not translation elegance; rewriting Git history can disrupt collaborators, signatures and automation. Offer reviewed correction paths rather than one universal destructive command.
Case: mixed Arabic and Latin
An Arabic subject follows an ASCII feat(ui): header, and the web page visually places punctuation unexpectedly. Compare the copied text with the source bytes, adjust presentation directionality without changing the example’s content, and test in the actual terminal. The educational note should explain visual order separately from parser order. This is a layout issue until a reproduced tool test establishes otherwise.
Case: accent length discrepancy
Two French subjects look identical but use different Unicode normalization forms. A project notices inconsistent behavior near a length threshold. Keep the examples distinct in testing, document the observed rule behavior and avoid claiming that the displayed count is universal across tools. A localized guide can recommend controlled input testing rather than encouraging readers to remove diacritics indiscriminately.
Case: warning treated as blocker
A translated help page describes a warning-level rule as an error that always blocks commits. Compare the actual rule level, command exit behavior and the surrounding CI policy. Rewrite the explanation to identify the observed effect. This distinction matters because contributors may spend time rewriting valid history to satisfy advice that the repository itself does not enforce.
Case: misleading screenshot
A screenshot of terminal output has had its English diagnostic replaced with a fluent translation, although upstream commitlint was never configured to emit that text. Label the image as illustrative or show a genuine command transcript with a translated caption. The reader must know whether a message is an actual CLI string, a translation of its meaning or a proposed UI customization.
Case: translated config key
An editor rewrites the JSON key rules as an equivalent word in the target language. The example is no longer executable. Restore the original key and add a plain-language description underneath. Configuration property names belong to the software interface; explaining those names is localization, whereas renaming them without software support is an accidental change to code.
Case: typos in options
A content management system turns –from into a typographic long dash sequence in a tutorial. A reader copies the sample and the CLI rejects the option. Use proper code formatting, test final-page copying and keep flags literal. This is a publishing QA failure, not a commitlint parser defect. Avoid broadly disabling editorial typography if a limited code-format fix works.
Case: release notes misclassified
An English commit header says feat but the translated changelog renders it as a bug fix because the subject mentions a defect. Review the code and release classification with a maintainer. Keep the commit evidence traceable, revise only the reader-facing explanation, and make no unsupported compatibility claims. This illustrates why a parser result is useful metadata but not a substitute for a technical editor.
Frequently asked questions
Can commitlint translate my commit messages?
No. It validates messages against configured rules. Translation happens in documentation, contributor communication or separate publishing systems; commitlint does not supply a general language-translation workflow.
Do all Conventional Commit subjects have to be in English?
No universal requirement follows from the convention. A repository may impose additional rules. Keep required machine tokens stable and check the actual configuration before advising on subject language.
What does type-enum mean?
It names a rule commonly used to constrain allowed type values. Translate the explanation, retain the literal identifier and inspect the repository’s approved list. Do not assume the set is identical across all projects.
Is –default-config suitable for production CI?
It can help with a one-off check when no rules are found, according to the CLI reference. Production workflows should use their deliberately selected and reviewed configuration, not an accidental fallback.
Why does a command pass locally but fail in CI?
Compare installed versions, configuration resolution, selected commit range, checkout history and wrapper scripts. The same message may be tested under different contexts; the visible output alone is not enough.
What is the safest way to localize a screenshot?
Preserve genuine output or mark illustrative output explicitly. Translate the caption and explanation, retain rule identifiers, and provide accessible selectable text for the key diagnostic.
Can I rewrite old commits to correct type spelling?
Not as a universal recommendation. Shared history, signed commits and automated workflows can be affected. Follow repository policy and coordinate with maintainers before changing published history.
Does a passing commit prove a nonbreaking release?
No. The tool tests configured message rules; semantic compatibility and release impact still require human code review and, where appropriate, compatibility tests.
Should I translate scope names?
Only if the repository configuration deliberately recognizes the translated identifier. Otherwise preserve configured scope tokens in executable examples and explain their meaning next to them.
What should I verify before publishing a translated tutorial?
Test copied commands, configuration keys, a passing case, several failures, Unicode examples, mobile presentation, accessibility, and links to maintained documentation. Record any version-specific differences.
Source documentation and next reading
Check the official commitlint CLI reference, rules configuration guide and Conventional Commits specification. For the separate problem of translating generated changelogs, see the git-cliff localization guide. These resources address related but distinct stages of the release communication process.