Translate Like a Pro | 11170 — Lefthook CLI Localization: Git Hooks, Pre-commit Jobs, Staged Files, Configuration and Unicode QA

How do you translate Lefthook CLI documentation, Git hook configuration, pre-commit diagnostics and staged-file commands without changing what developers are asked to run? This practical guide explains how to localize Lefthook for international engineering teams, including the difference between Git hook names, configurable jobs, command output and human-facing messages. It is written for technical translators, developer educators, documentation maintainers and reviewers who need precise, usable instructions rather than word-for-word substitutions.

Lefthook is a Git hooks manager that runs configured jobs when events such as pre-commit or pre-push occur. It reads a configuration file such as lefthook.yml, installs hook entry points, and invokes programs including formatters, linters and tests. A translation may describe those actions in any appropriate language, but strings such as lefthook run pre-commit, {staged_files}, YAML keys, file extensions and exit codes must continue to mean the same thing to the tool.

The reader will learn a safe documentation workflow: identify which text humans read and which text software interprets, preserve runnable syntax, describe Git’s index accurately, test translated examples on real repositories, and review Unicode, quoting and right-to-left layout. The quick checklist below comes first, followed by worked cases, troubleshooting, practical exercises and frequently asked questions so teams can use this article as both a learning guide and a quality-control reference.

Quick action checklist

Keep Git hook identifiers such as pre-commit and pre-push unchanged inside executable code; translate their explanations, not their byte sequences.
Treat lefthook.yml, jobs, run, glob, stage_fixed, parallel, root, files and {staged_files} as configuration or template syntax when they appear in runnable material.
Explain whether a command reads files, modifies the working tree, stages fixes or blocks a Git operation, rather than promising that all checks are harmless.
Test each localized example with the documented Lefthook version and a small disposable Git repository before publication.
Separate warnings about policy from proof of security or quality; passing a hook is not a substitute for CI, review or tests.

What Lefthook does and why translation is not just word choice

A Git hook is a local program Git may execute at particular points in a workflow. Lefthook manages those entry points and helps projects run configured jobs consistently. In translated documentation, distinguish installation of hook scripts from installation of project dependencies. A developer may install the Lefthook binary successfully yet still need to run lefthook install in a particular checkout. Likewise, changing lefthook.yml does not normally require a reinstall because the installed hook reads the configuration when invoked. The distinction prevents translators from turning a one-time setup step into unnecessary repeated work. A helpful explanation starts with the user’s situation: freshly cloned repository, configured jobs, staged changes, and the effect of Git attempting to create a commit.

Use a two-column glossary during editing: one column for literal tool terms and one for clear explanations. For example, do not translate the code token pre-commit into an invented command; explain that it runs before Git completes a commit. Explain that a failing check can interrupt the attempt, but the developer may still inspect and change files. This is a description of control flow, not a judgment on the developer’s skill. A good localized guide makes the sequence observable so an unfamiliar reader can reproduce it without guessing.

The Git index: staged is not merely saved

The phrase staged files is often mishandled because many languages use one ordinary verb for saved, uploaded, prepared and selected. In Git, staging means adding selected content to the index for the proposed commit. A formatter can modify a file in the working tree without those modifications necessarily being part of the staged snapshot. If documentation calls every modified file staged, a reader can unknowingly commit one version while looking at another. Translate the concept before choosing a noun. Provide a familiar example: a developer stages a JavaScript file, then edits it again; Git now has a staged version and a newer working-tree version. The hook must be interpreted with that split in mind.

Explain {staged_files} as a Lefthook template placeholder used in command configuration, not prose to translate or a shell variable to rename. Show the reader how file matching, filtering and quoting affect what reaches a formatter. When a command makes edits, ask whether stage_fixed is appropriate and whether it is limited to the pre-commit hook. The translator should not imply that a successful formatter always updates Git’s index. Reviewers can compare git diff and git diff –cached in a test repository to validate the explanation without depending on translation intuition.

Configuration language and YAML structure

Lefthook configuration can be expressed in YAML, where indentation, list markers, quoted strings and key spelling carry meaning. Translate surrounding prose and comments cautiously, but preserve executable keys and template placeholders exactly. A label such as jobs in a YAML example is not a casual word that can be replaced by a synonym. A localized guide should distinguish comments intended for human readers from data that the parser consumes. The difference is important when examples include a glob pattern, a root directory, a script runner or a shell command assembled from multiple arguments. If a paragraph says to edit the root property but the sample shows root as translated prose, the reader cannot perform the task.

Copy-and-paste reliability matters. Straight quotation marks and normal ASCII hyphens may be required in shells, while typographic punctuation can be appropriate in the explanation. Code fences need stable left-to-right presentation even when the prose is right-to-left. Preserve braces around {staged_files}, and do not introduce invisible non-breaking spaces into command names or paths. Run lefthook validate after any meaningful change to a sample; validating documentation is more useful than admiring a translated screenshot.

Install, run, validate and dump are different operations

Documentation that translates command names as if they were interchangeable creates operational errors. lefthook install sets up Git hook entry points; lefthook run pre-commit invokes configured behavior for a named hook; lefthook validate checks the configuration; lefthook dump exposes the resolved configuration. These are different verbs with different outputs and side effects. Writers should describe them in separate steps and avoid instructing users to run a hook simply because they want to inspect configuration. The tool’s documentation also notes interaction with core.hooksPath, which may require deliberate resolution rather than blindly forcing installation.

A translated setup guide should say whether a step is safe to run in an existing repository and what to inspect if it fails. If core.hooksPath has been customized for corporate tooling, changing it may remove an expected integration. Explain that force or reset options should be chosen with understanding of the local environment, not merely because a quickstart command printed a warning. When the same guide serves Windows, macOS and Linux, spell out platform-sensitive commands and avoid claiming that every shell parses quotes identically.

Why parallel execution changes the story

A configuration may allow several jobs to run in parallel. Parallel improves throughput but also means output can be interleaved and operations may overlap. Translators should not turn an instruction such as run jobs in parallel into do these steps one after another. Nor should a localized guide guarantee deterministic ordering where the configuration makes no such guarantee. If two tools modify the same staged file, the real question is whether the job graph is safe; translation must preserve that concern. Explain sequential groups, piped groups and independent jobs in terms a developer can verify without memorizing implementation internals.

An example works better than an abstract definition. Suppose a hook runs a formatter and a linter against one file. If both operate simultaneously, the linter might see a transient version. A responsible guide shows how the team can decide whether a serial chain is needed and then verify results with a test commit. Avoid suggesting parallel means simultaneous on every machine or that faster always means correct. These are engineering trade-offs, not linguistic preferences.

Globs, paths and operating-system assumptions

Globs select sets of files; they are not general descriptions of file types. A pattern like *.ts and a pattern matching nested directories may produce different coverage depending on the tool and context. Preserve metacharacters, separators and braces within examples. Explain what files should match and, just as importantly, what should not. A relative path under a root setting may not refer to the same location as a path relative to the repository root. This becomes important in monorepos containing frontend, backend and shared packages. Translators should express path scope explicitly instead of saying vaguely that the hook checks the project.

Use small representative directory trees in multilingual documentation and test on a clean copy of the repository. Note where an instruction depends on a POSIX shell, PowerShell, Windows path conventions or glob evaluation within Lefthook rather than within a shell. Do not localize extension strings such as .tsx or replace a slash with localized punctuation. Readers should be able to predict whether an unmatched pattern means no work, a warning or a broken configuration by consulting the tool’s actual behavior for their version.

What stage_fixed really promises

The stage_fixed option is easy to mistranslate into automatically fixes everything. The documented purpose is narrower: for pre-commit work, Lefthook can run git add for relevant files after the command or script, applying the described file filters. The fact that a tool restages content has consequences. It may include formatter output in the commit, and failure to stage should cause the hook to fail rather than allow the commit to proceed quietly. A translator must not describe this as background saving, upload or review approval. The option changes which file content enters the proposed commit.

Teach readers to inspect their index after a formatter runs. A beginner may see a green message and assume that only the lines originally staged are included; depending on tooling and staging behavior, that assumption needs verification. Translate warnings about partial staging with particular care. Where a workflow requires precise partial commits, a team may choose a different approach to automated fixes. The localization should help readers ask that question before activating automation across a large repository.

Exit status, failures and bypasses

A hook that exits nonzero can prevent a Git operation from completing. The text explaining this should not imply that the developer lost their changes or that an error automatically means malicious code. Output can come from Git, Lefthook or a child process such as ESLint, a unit-test runner or a formatter. Translate only user-facing diagnostics within the boundary of the relevant component; do not change the child tool’s machine-readable output or rule identifiers. Differentiate a syntax error, tool-not-found error, failed test and policy rejection, because each leads to a different next action.

The Lefthook documentation illustrates LEFTHOOK=0 as a way to skip hooks for a command. A translation should not promote bypassing checks as a routine solution, especially in shared repositories. Explain that bypasses may be legitimate for emergency recovery but must be governed by team policy and followed by equivalent checks when appropriate. State plainly that local hooks can be skipped and that CI remains an independent enforcement layer. This makes security and quality claims proportionate.

Versioned documentation and installation channels

Lefthook can be installed through several ecosystems, including package managers and standalone distributions. The exact install command, automatic postinstall behavior and available configuration features can change with versions. Translate commands for a known release and provide a path to the official documentation rather than asserting a permanently universal recipe. When a package install invokes hooks automatically, distinguish the dependency-install phase from repository hook setup. For some users an unexpected postinstall operation is important operational information, not a minor footnote.

A useful localized page states what was tested, what assumptions apply to the shell and repository, and where the authoritative command reference lives. For version-sensitive options such as newer job configuration, editors should check the installed executable’s help output rather than backfilling an older tutorial with current terminology. Maintain source and translated examples in the same revision so changes are traceable. Readers deserve an honest boundary between stable concepts and implementation details that may move.

Unicode, bidi and accessibility quality assurance

International documentation must survive copying from browsers, mobile screens, PDFs and messaging applications. Unicode normalization, invisible directional marks and typography substitutions can damage commands that look visually correct. A right-to-left paragraph can contain a left-to-right code fragment, but the command itself must retain its logical character order. Store executable examples as code, use sensible language tags in the publishing system, and check screen-reader order for mixed scripts. Localize explanations of file paths without transliterating machine identifiers. For user-facing error strings, preserve placeholders and formatting tokens in their original structure.

Review code in a plain text editor and copy it into a real shell; a screenshot alone is insufficient. Check curly versus straight quotes, en dash versus hyphen, full-width punctuation, non-breaking spaces and visually confusable characters in command names. Where locale-specific quotation is necessary in a sentence, keep it outside the code fence. Reviewers should also ensure headings and alt text convey actual tasks, not just keyword strings. Accessibility and operational correctness reinforce each other.

Terminology governance across repositories and languages

A mature team uses a terminology register rather than inventing a new equivalent for pre-commit on every page. The register should mark exact code tokens, recommended natural-language translations, prohibited ambiguous expressions, and sample contexts. Git index, hook, working tree, stage, job, script, glob and exit status are worth separate entries because they have distinct meanings. Translator notes should explain why an apparent synonym is wrong in this system. Keep the glossary small enough to use; link to deeper Git explanations when novices need help.

Approve terms through a review involving at least one developer who actually uses the workflow. That person can test whether the localized instructions produce the described results, not merely whether sentences sound fluent. Whenever the underlying tool changes a feature, update the glossary and its examples together. Avoid creating rival pages that repeat the same full command reference; a specialized localization article should focus on translation decisions, failure modes and reproducible tests.

A reliable review and publication process

Begin by reading the source documentation as a procedure: identify the reader’s starting state, expected command, output and next decision. Build a nonproduction sample repository with a staged file, a formatter and a failing check. Then draft the translation, preserving exact tokens as code and keeping environment assumptions visible. Have a second reviewer run the commands without consulting the original language. Record every mismatch as either a translation problem, documentation problem or version problem. Fix the explanation, not the tool’s observed behavior, unless the published example is genuinely incorrect.

Before release, inspect search results and on-site coverage to choose a narrow page purpose. A guide about Lefthook localization should not masquerade as a comprehensive Git tutorial, a product comparison, or an unrelated lesson in language grammar. Publish useful headings, real examples, short summaries and citations to official project documentation. Follow up only when the tool changes or reader questions reveal real gaps. The goal is enduring utility, not repeated paraphrases of the same page.

Worked translation and troubleshooting cases

Case 1: Fresh clone

An engineer has cloned a repository and sees lefthook.yml but no local hook activity. Explain that tracked configuration and installed local Git hook entry points are separate; direct the reader to the project’s supported setup command. Do not imply that cloning a file automatically activates every local hook on every installation.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Test in a disposable clone and inspect .git/hooks without changing shared repository settings. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 2: No config yet

A beginner runs lefthook install in a folder with no existing configuration. Document the documented behavior of creating an empty lefthook.yml and installing available configured hooks when appropriate. Do not present an empty file as evidence that effective tests were configured.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Compare expected and actual files after setup, then add one named job and retest. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 3: Named pre-commit hook

A guide uses the English phrase before commit beside an executable hook identifier. Keep pre-commit literal in commands and translate the natural-language description around it. A translated command token may refer to a nonexistent hook and make the tutorial impossible to follow.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Run the displayed command as copied from the final translation. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 4: Staged and unstaged edits

A developer stages one version of app.ts and changes the working copy again. Describe both the index snapshot and working-tree content; explain which version the configured command handles. Collapsing these states into saved file can lead to a commit containing unexpected content.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Inspect git diff and git diff –cached before and after the hook. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 5: Placeholder preservation

An editor replaces {staged_files} with localized words in a YAML example. Preserve the placeholder exactly and explain its meaning outside the runnable line. The translated text becomes an argument instead of the intended file list.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Run lefthook validate and an end-to-end hook in a test repository. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 6: Glob mismatch

A CSS linter receives a pattern that does not match nested stylesheets. Explain matching scope and keep wildcard punctuation unchanged. A broad phrase like all CSS files may promise coverage the glob cannot deliver.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Plant matching and nonmatching filenames and observe which are processed. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 7: Parallel formatters

A single hook contains two jobs that can both edit the same source file. Explain the risk of overlapping writes and where a serial sequence may be more appropriate. The translation must not call parallel execution a guaranteed safe optimization.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Test multiple runs and compare resulting files for stability. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 8: Restaging fixes

A formatter modifies a file and stage_fixed is enabled. Explain that this setting concerns staging relevant modified files after a job and is specific to pre-commit. The phrase automatically corrects the commit obscures whether extra changes enter the index.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Review staged changes after a deliberate formatting failure. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 9: Customized hooksPath

The repository already sets core.hooksPath to a central hooks directory. Explain the configuration conflict and why force or reset flags are deliberate choices. Blindly resetting the path may bypass organization-managed checks.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Inspect git config –get core.hooksPath before changing anything. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 10: Validate versus run

A localized page tells readers to run pre-commit merely to check YAML syntax. Separate lefthook validate from executing the hook’s programs. The latter may modify working files or run expensive tasks.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Compare commands in an empty test project and document observed side effects. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 11: Dump resolved configuration

A project extends local configuration and readers cannot tell which jobs are effective. Explain that lefthook dump can help inspect resolved configuration instead of guessing from one file. Readers may be looking at only part of the effective job list.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Compare the dumped configuration with the expected merged inputs. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 12: Hook failure

An ESLint process exits unsuccessfully and Git refuses to finish the commit. Attribute the failure to the child check and describe the subsequent Git effect. Calling every failure a Lefthook bug delays the appropriate diagnosis.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Reproduce the child command directly and preserve its exit status. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 13: Missing executable

The hook references a command absent from a contributor’s machine. Translate the remediation as environment setup, not a request to rename the command. Replacing a literal binary name makes the error harder to search and fix.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Inspect PATH and the project’s declared dependencies. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 14: Windows shell syntax

The sample contains POSIX-style environment variable assignment and a Windows reader copies it verbatim. State the shell assumption and provide a verified platform-specific explanation. A command can be correct in Bash while failing in PowerShell.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Test in the named shell or mark the example as platform-limited. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 15: Right-to-left language

An Arabic-language instruction contains a mixed-direction hook command and filename. Keep the executable fragment as directional code and check actual character order. Visual direction can disguise reordered punctuation or braces.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Copy the final rendered command into a plain editor and run it. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 16: Smart punctuation

An editor automatically substitutes curly quotes and an en dash in command examples. Use plain-text literals inside code and leave typographic styling to the prose. The command may fail even though the printed page appears polished.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Compare source bytes with copied bytes. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 17: Sensitive output

A pre-commit scanner prints a secret-like string in diagnostic output. Replace real secrets with clearly marked synthetic samples; retain accurate explanation of exit codes. Translations should not create a new leak in screenshots, examples or search snippets.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Review logs and screenshots before public release. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 18: CI versus local hooks

A team claims that passing a local pre-commit hook proves the repository is secure. Explain that local hooks may be bypassed and CI plus review provide additional controls. Overclaiming assurance is a safety error rather than merely poor style.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Check that assurance language matches actual enforcement and access rights. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 19: Monorepo root

Frontend and backend commands run from different subdirectories. Explain root and relative-path scope without changing executable directory names. Incorrect path translation sends the command to the wrong package.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Test from a fresh checkout with more than one root. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 20: Empty file selection

The hook runs with no staged files matching a job’s pattern. Explain the documented no-match behavior for the tested version without promising that a check ran. A green terminal does not prove all desired files were inspected.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Add one positive-control matching file and compare results. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 21: Skip instruction

A developer finds LEFTHOOK=0 in a translated troubleshooting guide. Describe a governed bypass and why it is not a regular substitute for repair. An innocent-sounding skip tip can weaken local checks.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Ask the repository maintainer what compensating check is required. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 22: Error message translation

A child’s formatter message and Lefthook wrapper message appear together. Attribute each message to the software that emitted it and keep rule identifiers intact. Misattribution produces searches and support requests against the wrong tool.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Label sample output and test against the versions shown. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 23: Generated docs

A documentation builder injects terminal output into a multilingual page. Distinguish commands, outputs and explanatory prose, and sanitize volatile paths and identities. A literal absolute path from one developer’s machine misleads readers elsewhere.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Regenerate output in a controlled environment with synthetic data. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Case 24: Review handoff

A translator is fluent but has never staged a partial Git change. Provide a runnable acceptance test and pair the language reviewer with a developer. Fluent words cannot certify an untested operational sequence.

A practical localization review should put the source sentence beside the translated sentence and identify the exact action expected of the reader. Use the staged/unstaged scenario as a go-or-no-go publication check. The reviewer should record the observed command, the relevant file state, the resulting message and what the developer must do next. If those facts cannot be reconstructed from the translated page, expand the explanation rather than replacing a machine token with a more familiar-looking word. The example must work for a newcomer who sees only the translated guide.

Frequently asked questions

Should I translate Lefthook commands?

No. Keep runnable CLI names, flags, Git hook identifiers and configuration keys intact. Translate the surrounding instructions and error explanations. If a product officially offers localized interface strings, translate only through that supported mechanism and test the output. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

Is a Git hook the same as a GitHub Actions workflow?

No. A Git hook is associated with Git operations in the repository environment. GitHub Actions workflows are automation defined for the GitHub platform. The concepts may support each other, but the execution contexts, bypass options and logs are not interchangeable. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

Does changing lefthook.yml require reinstalling hooks?

Normally the installed hook reads configuration when it runs, so documentation should not demand a reinstall after every configuration edit. Check the official guidance and the setup of the specific repository if hooks are missing or core.hooksPath has been customized. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

Why can a formatter alter my commit?

A formatter may modify files, and stage_fixed can stage relevant changes during pre-commit. Users should examine both the working tree and index after automatic fixes, particularly if they made partially staged changes. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

Does a green hook guarantee secure code?

No. Passing checks means the configured jobs did not report a blocking problem under their execution conditions. It cannot prove complete test coverage, absence of vulnerabilities, or enforcement against people who can bypass local hooks. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

What should a translator do with {staged_files}?

Keep the brace-delimited placeholder unchanged in executable examples. Explain it as the tool’s template for staged file arguments. Verify the file selection in a test repository, including paths with spaces. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

How should code look in Arabic or Hebrew documentation?

Place commands in code styling with preserved left-to-right character order and check rendered copies in the target reading environment. Translate explanatory sentences without introducing invisible direction characters into tokens. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.

Where can readers verify options?

Consult https://lefthook.dev/ and the command-specific docs, then compare the help output of the installed executable. Treat older examples as versioned material rather than universally current rules. This is a documentation decision with an observable result: test the examples in a clean, nonproduction repository, and have a second reader check whether the intended step and its expected outcome are unambiguous. Prefer precise limitations to a sweeping claim that every configuration and platform behaves the same way.