Hadolint CLI localization means translating the explanations around Dockerfile linting without changing the Dockerfile, its command syntax, its diagnostic identifiers or the decisions a build pipeline makes. This guide explains how to translate Hadolint warnings, Dockerfile rule messages, severity levels, ignored checks and configuration advice for international engineering teams.
When people search for how to translate Hadolint output or localize Dockerfile linter documentation, they usually need more than an English-to-another-language glossary. They need to distinguish a linter warning from a Docker image build failure, understand which text is safe to translate and preserve rule IDs such as DL3006 and ShellCheck identifiers beginning with SC. A mistranslated diagnostic can cause someone to change the wrong instruction.
The following chapters start with a readable Dockerfile example and progress through lint commands, rules, suppression choices, severity, structured reports, CI behavior, troubleshooting and Unicode quality assurance. The goal is not to teach readers to bypass checks. It is to help a reader in any country understand precisely what a Hadolint result says, why it matters, what it does not prove and how to make a defensible edit.
- Read this if: you translate Dockerfile linter logs, developer documentation or CI warning messages.
- Preserve exactly: commands, paths, Dockerfile keywords, rule IDs, config keys and machine-readable schemas.
- Translate carefully: rule explanations, recommended actions, human reports and learner instructions.
- Check separately: lint result, build result, runtime validation, and security evidence.
- Use with: the installed Hadolint release and its published documentation.
How to use this guide
Read the first five chapters to learn the evidence model, then follow the chapters closest to your real translation problem. Each worked situation is fictional and uses harmless sample files. Do not paste commands containing credentials or private registry addresses into public translation services. The upstream Hadolint project and documentation define actual behavior for the version you use; the examples here explain how to preserve their meaning across languages.
1. A linter is not the image builder
Hadolint parses Dockerfile instructions, applies its own rules and also uses ShellCheck knowledge for supported shell fragments inside RUN instructions. That is a static check of a written build recipe, not proof that the resulting image was successfully built, is secure in production or contains the expected application behavior.
Worked situation. A translator receives the sentence ‘Dockerfile checks passed’ beside a separate CI stage showing a failed image build. The correct localized explanation keeps the two stages separate: linting found no blocking rule violations according to its configuration; the build still failed and needs its own log.
Common mistranslation. Do not render lint success as ‘the container has passed security certification.’ That conclusion expands the evidence and misleads operations teams. Better interpretation. Say which file was linted, which rule set and severity threshold applied, and whether a real image build was separately tested.
For translation work, the phrase a linter is not the image builder is not simply a vocabulary item. It is a decision boundary. Read the original finding, check the actual command or file, and decide whether the audience needs an explanation of a fact, a recommendation or a limitation. Those three kinds of sentences should not merge. When a reader mistakes a recommendation for proof, the text may sound confident but the engineering decision becomes less reliable. A good translation makes the evidence easy to find and the next safe action easy to understand.
Reviewer exercise. Ask a reviewer to underline the exact observation and circle every claim about runtime behavior. Remove claims not supported by the lint report. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
2. First command and path interpretation
The basic command takes a Dockerfile path, for example hadolint Dockerfile. The path is an input reference; capitalization, whitespace and directory structure are operational data rather than prose. On a case-sensitive filesystem changing Dockerfile to dockerfile can identify a different object or cause a file-not-found failure.
Worked situation. In an onboarding translation a screenshot shows ‘hadolint services/api/Dockerfile’ but the prose changes the path to a localized folder name. The student copies it and gets an error. Translate ‘check the API service Dockerfile’ but keep the real command and repository path unchanged.
Common mistranslation. A translated example must not quietly invent directories or suggest that the command repairs the source automatically. Better interpretation. Separate the natural-language instruction from a code block, and say that the path is a placeholder only when it truly is one.
A useful teaching exercise is to give two readers the same command and ask them to explain the result independently. One should focus on what the tool inspected; the other should focus on what action the maintainer is being invited to consider. Compare their answers with the original documentation. If they disagree about the object, scope or certainty, the translated wording needs another pass. This review is especially helpful when the audience has limited experience with container builds or when several teams use the same shared build pipeline.
Reviewer exercise. Have another reader copy the command character for character and identify which parts are commands, paths and narrative words. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
3. Dockerfile grammar versus prose
Dockerfile keywords such as FROM, RUN, COPY, WORKDIR, USER, CMD and HEALTHCHECK carry meaning to the builder. They are not vocabulary flashcards to translate in executable examples. Human-facing comments and surrounding documentation can be translated, provided it remains clear which lines are code and which are explanatory remarks.
Worked situation. Consider a teaching sample that says FROM example/image:1.0 followed by WORKDIR /app. A localized paragraph can explain the base-image reference and working directory in the target language. Replacing FROM with a target-language word inside the Dockerfile would invalidate the example.
Common mistranslation. The common failure is partial localization: only one token changes, the example still looks plausible and the command later fails mysteriously. Better interpretation. Keep exact code in a code block and provide a nearby interpretation in clear language. If you show a translated comment, say it is commentary.
Make the message work in a real troubleshooting conversation. A developer might read the translated sentence under time pressure and ask, “What do I open, what do I compare, and what can I change without losing information?” The answer should point to a concrete source such as the Dockerfile, configuration or raw report. It should not send the reader to a vague security slogan. Include a stopping point: when the information is incomplete, the safe response is to inspect the original output before editing the file.
Reviewer exercise. Copy the code to a parser or trusted test fixture, then review only the explanatory text for language quality. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
4. Understand DL and SC identifiers
Hadolint rules conventionally use DL-prefixed identifiers, while common ShellCheck diagnostics use SC-prefixed identifiers. A diagnostic ID is a stable reference that connects documentation, ignore lists and reports; its letters and digits should remain identical even when the surrounding message is translated.
Worked situation. A reader encounters DL3006, which concerns explicitly tagging base images, and an SC warning in a RUN shell fragment. A localized glossary should retain both IDs and explain that they come from related but distinct checking layers rather than treating every message as one universal Dockerfile rule.
Common mistranslation. Translating a rule ID into a memorable local abbreviation breaks lookup and can make an ignore setting refer to nothing. Better interpretation. Preserve ID spelling and case, explain the relevant rule in natural language, and link to the exact documentation for the release being used.
A precise localization can be tested like a technical change. Preserve the English diagnostic alongside the target-language rendering in a review fixture. Check that identifiers, severity, references and actions remain traceable. Then hide the English sentence and ask a fluent target-language reader what the message authorizes and what it does not claim. A translation passes this exercise only when the reader reaches essentially the same practical interpretation. Elegant wording without that equivalence is not sufficient.
Reviewer exercise. Check a few rendered examples by searching the ID in the source documentation and in the target-language article. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
5. Base image tags and version claims
Hadolint includes checks about base image tagging, such as DL3006 for explicit tags and DL3007 concerning use of latest. A tag is a selector, not a guarantee of immutability or complete security. It is important not to translate ‘explicitly tag the version’ into a false promise that every image with a tag is permanently fixed.
Worked situation. Imagine the Dockerfile FROM example/base:latest. A localized review should explain that ‘latest’ can resolve differently later, and that a team may need a deliberately chosen version or digest. Avoid replacing example/base:latest with a real vendor name that readers might mistakenly trust.
Common mistranslation. Do not equate a rule warning with proof that the image already changed or was compromised. Better interpretation. Describe the reproducibility risk and the team’s need to choose and verify an appropriate reference under its own release policy.
For translation work, the phrase base image tags and version claims is not simply a vocabulary item. It is a decision boundary. Read the original finding, check the actual command or file, and decide whether the audience needs an explanation of a fact, a recommendation or a limitation. Those three kinds of sentences should not merge. When a reader mistakes a recommendation for proof, the text may sound confident but the engineering decision becomes less reliable. A good translation makes the evidence easy to find and the next safe action easy to understand.
Reviewer exercise. Ask a second engineer whether the translation distinguishes a tag, a digest and an installed package version. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
6. Package installation and pinning
DL3008 addresses pinning versions in apt-get install instructions; related lint rules address package-manager hygiene. A translated guide should say exactly which package manager and command are involved. Broad advice such as ‘always pin every dependency in every environment’ ignores the practical policy decisions and different package ecosystems teams must make.
Worked situation. A sample RUN apt-get update && apt-get install -y … can trigger discussion about version selection, cache behavior and image reproducibility. In translation, preserve shell operators and flag spelling. Explain why a team chooses an update strategy rather than editing the command to satisfy a prose preference.
Common mistranslation. The wrong rendering confuses image-layer instructions with an interactive workstation setup and invites a reader to edit unrelated files. Better interpretation. Keep the command, Docker build context and package-version decision together, but distinguish the linter recommendation from a compulsory universal law.
A useful teaching exercise is to give two readers the same command and ask them to explain the result independently. One should focus on what the tool inspected; the other should focus on what action the maintainer is being invited to consider. Compare their answers with the original documentation. If they disagree about the object, scope or certainty, the translated wording needs another pass. This review is especially helpful when the audience has limited experience with container builds or when several teams use the same shared build pipeline.
Reviewer exercise. Have a reviewer identify what the command actually runs and whether the advice needs a qualification about package repositories. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
7. WORKDIR and filesystem effects
DL3000 concerns absolute WORKDIR paths, and DL3003 concerns changing directories with cd rather than WORKDIR. These rules teach clarity in the image’s filesystem context. A path like /workspace is executable data and should not be translated into an ordinary phrase about a desk or office.
Worked situation. A manual shows WORKDIR /app next to a note ‘set the current directory for following instructions.’ A translator can explain the effect for novice readers but must not imply that the directory on the reader’s host computer is necessarily changed.
Common mistranslation. A particularly harmful mistranslation silently swaps container-internal paths with host filesystem paths. Better interpretation. Name which environment the path belongs to, show the code untouched and explain how subsequent instructions use the working directory.
Make the message work in a real troubleshooting conversation. A developer might read the translated sentence under time pressure and ask, “What do I open, what do I compare, and what can I change without losing information?” The answer should point to a concrete source such as the Dockerfile, configuration or raw report. It should not send the reader to a vague security slogan. Include a stopping point: when the information is incomplete, the safe response is to inspect the original output before editing the file.
Reviewer exercise. Test whether a reader can distinguish a Dockerfile WORKDIR directive from a shell cd command and from a local terminal’s directory. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
8. Root user and privilege messages
Some Hadolint checks address user selection, including DL3002 concerning the last user being root. The core issue is how the resulting container process is configured, not an accusation about the human operator. A translation should avoid moral language such as ‘administrator is unsafe’ when the rule is about a specific runtime privilege context.
Worked situation. For a Dockerfile that ends without an explicit USER directive, a lint warning can prompt an engineering review. The localized remediation should explain non-root execution where appropriate, while recognizing that permissions, ports and file ownership may require planned changes and testing.
Common mistranslation. The dangerous shortcut is to translate ‘should not be root’ as a command to remove every privilege in all environments without verifying application requirements. Better interpretation. Explain the rule, the default or inherited execution identity where applicable, and the need for functionality and security validation.
A precise localization can be tested like a technical change. Preserve the English diagnostic alongside the target-language rendering in a review fixture. Check that identifiers, severity, references and actions remain traceable. Then hide the English sentence and ask a fluent target-language reader what the message authorizes and what it does not claim. A translation passes this exercise only when the reader reaches essentially the same practical interpretation. Elegant wording without that equivalence is not sufficient.
Reviewer exercise. Ask a reviewer to describe exactly who or what is root: the container process, the host user or the CI account. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
9. Shell fragments within RUN
Hadolint incorporates ShellCheck analysis for supported shell code embedded in Dockerfile RUN instructions. The words ‘shell’, ‘RUN’ and ‘script’ can be misleading if a translation treats them as interchangeable. A RUN instruction is part of a build recipe; shell semantics depend on its form and configured shell.
Worked situation. Consider RUN echo “$HOME” followed by a more complex command containing variables, quoting and redirection. The explanatory language may be translated freely, but changing quote marks, dollar signs, backslashes or operators inside an example can alter what executes.
Common mistranslation. A fluent translation that substitutes typographic quotation marks inside code may make the tutorial impossible to reproduce. Better interpretation. Use monospace formatting for syntax, preserve escape sequences and explain precisely which text is prose rather than the shell interpreter’s input.
For translation work, the phrase shell fragments within run is not simply a vocabulary item. It is a decision boundary. Read the original finding, check the actual command or file, and decide whether the audience needs an explanation of a fact, a recommendation or a limitation. Those three kinds of sentences should not merge. When a reader mistakes a recommendation for proof, the text may sound confident but the engineering decision becomes less reliable. A good translation makes the evidence easy to find and the next safe action easy to understand.
Reviewer exercise. Copy examples into an authorized disposable environment and compare the shell tokenization with the source before publication. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
10. Severity labels and thresholds
Hadolint can classify findings by severities such as error, warning, info and style. Its failure-threshold setting controls which severity causes a failing exit status, while findings below the threshold may still be printed. A localized report must distinguish ‘displayed’ from ‘blocking’ and should not call a warning a fatal error merely because it appears in red.
Worked situation. An engineering team sets a threshold at warning. A style message remains visible but is not necessarily what failed the pipeline. The translated summary should indicate the configured gate rather than describe every displayed line as a stop condition.
Common mistranslation. Rendering ‘failure threshold’ as a vulnerability severity score would merge two unrelated ideas and produce poor prioritization. Better interpretation. Preserve the technical configuration term and describe the practical rule: which findings are reported and which decide the exit code.
A useful teaching exercise is to give two readers the same command and ask them to explain the result independently. One should focus on what the tool inspected; the other should focus on what action the maintainer is being invited to consider. Compare their answers with the original documentation. If they disagree about the object, scope or certainty, the translated wording needs another pass. This review is especially helpful when the audience has limited experience with container builds or when several teams use the same shared build pipeline.
Reviewer exercise. Pair the translated report with a test run that includes findings on both sides of the chosen threshold. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
11. Ignored rules and inline pragmas
Hadolint supports ignoring specified rules and recognizes inline ignore pragmas such as # hadolint ignore=DL3006, subject to configuration. Ignore means the specified check is not reported in that context; it does not mean the underlying code became safe or the concern was resolved.
Worked situation. A team makes a conscious exception for a legacy image and records its reason. The localized policy should say which rule, which scope, why the exception is temporary or accepted, and how it will be reviewed. It must not present ignore as a magical repair command.
Common mistranslation. Never translate # hadolint ignore=DL3006 within executable examples or expand a narrow rule exception into a broad compliance waiver. Better interpretation. Keep exact pragma syntax and describe its consequences in a nearby sentence that an auditor could understand.
Make the message work in a real troubleshooting conversation. A developer might read the translated sentence under time pressure and ask, “What do I open, what do I compare, and what can I change without losing information?” The answer should point to a concrete source such as the Dockerfile, configuration or raw report. It should not send the reader to a vague security slogan. Include a stopping point: when the information is incomplete, the safe response is to inspect the original output before editing the file.
Reviewer exercise. Ask the reviewer what remains untested after suppression and how the team will know whether the original condition persists. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
12. Configuration files and precedence
Hadolint supports YAML configuration, including ignored rules, trusted registries and severity overrides. A config key is machine-readable; the prose describing its purpose is translatable. The reader also needs to know which configuration file or command-line option actually controlled a run.
Worked situation. In one project a CLI flag ignores DL3006 while a repository configuration overrides another rule’s severity. The localized guide should not collapse these into a single vague ‘settings were changed.’ Give the file path, active setting and resulting behavior, then show how to confirm it.
Common mistranslation. A translated example that alters ignored, trustedRegistries or override as key names can cause settings to be ignored. Better interpretation. Leave serialized keys and IDs unchanged; translate explanatory comments and connect each option to a verifiable observed outcome.
A precise localization can be tested like a technical change. Preserve the English diagnostic alongside the target-language rendering in a review fixture. Check that identifiers, severity, references and actions remain traceable. Then hide the English sentence and ask a fluent target-language reader what the message authorizes and what it does not claim. A translation passes this exercise only when the reader reaches essentially the same practical interpretation. Elegant wording without that equivalence is not sufficient.
Reviewer exercise. Review the exact sample with the installed version and verify what happened when more than one configuration source was supplied. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
13. Trusted registries are not guarantees
Hadolint offers trusted-registry-related checks or configuration, but a registry being allowed by policy does not mean that every image hosted there is malware-free, current or suitable for deployment. Language about trust must retain the policy scope and avoid overpromising a security result.
Worked situation. A corporate guide authorizes a set of registries for base images. In translation, say that a reference is drawn from an allowed registry under this check; do not say the downloaded image has been independently verified for all vulnerabilities.
Common mistranslation. The word ‘trusted’ can sound stronger in some languages than the technical policy intends. Better interpretation. Use an explicit phrase such as ‘registry permitted by this project’s lint policy’ when the target language otherwise implies universal assurance.
For translation work, the phrase trusted registries are not guarantees is not simply a vocabulary item. It is a decision boundary. Read the original finding, check the actual command or file, and decide whether the audience needs an explanation of a fact, a recommendation or a limitation. Those three kinds of sentences should not merge. When a reader mistakes a recommendation for proof, the text may sound confident but the engineering decision becomes less reliable. A good translation makes the evidence easy to find and the next safe action easy to understand.
Reviewer exercise. Ask a security reviewer whether the translated claim would still be true for a compromised yet allowlisted repository. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
14. Output formats and report consumers
Hadolint can emit more than human-friendly terminal text. Teams may use structured output or formats intended for CI consumers. Formatting, field names and paths can be part of a machine interface; translating them inside JSON or another report structure may break ingestion even when the sentence reads beautifully.
Worked situation. A team stores a structured lint report as an artifact while showing a localized summary to developers. The safest pattern is to keep the raw report unaltered and generate separate display text from known message fields with a tested language map.
Common mistranslation. Editing diagnostic keys in-place can break dashboards and obscure whether an error came from the original tool or the translation layer. Better interpretation. Define an immutable source-of-truth report and a separate human-readable localization surface; document how identifiers map between them.
A useful teaching exercise is to give two readers the same command and ask them to explain the result independently. One should focus on what the tool inspected; the other should focus on what action the maintainer is being invited to consider. Compare their answers with the original documentation. If they disagree about the object, scope or certainty, the translated wording needs another pass. This review is especially helpful when the audience has limited experience with container builds or when several teams use the same shared build pipeline.
Reviewer exercise. Round-trip sample reports through the actual consumer and compare counts, IDs, file paths and severity classes before release. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
15. Exit codes and CI gate decisions
A CI job often treats a nonzero exit code as failure. The exit code is a process result, not a translated adjective. A localized build log should explain why the job failed without falsely saying the application failed runtime testing or that every finding was a blocking violation.
Worked situation. A pull request check shows several lint messages and one failing job. The translator should connect the gate to the configured severity threshold and the tool’s actual exit status, while acknowledging unrelated execution failures such as missing files or malformed configuration.
Common mistranslation. Do not translate ‘nonzero’ into ‘critical’ or translate ‘success’ into ‘all risks eliminated.’ Better interpretation. Write one sentence stating the process outcome and a separate sentence identifying the evidence used to reach it.
Make the message work in a real troubleshooting conversation. A developer might read the translated sentence under time pressure and ask, “What do I open, what do I compare, and what can I change without losing information?” The answer should point to a concrete source such as the Dockerfile, configuration or raw report. It should not send the reader to a vague security slogan. Include a stopping point: when the information is incomplete, the safe response is to inspect the original output before editing the file.
Reviewer exercise. Test a passing Dockerfile, a known-rule violation and a tool invocation error, and confirm that the localized messaging keeps them distinct. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
16. Unicode, directionality and code fidelity
Arabic, Hebrew, Japanese, Korean, Indic scripts and accented Latin text can all appear in localized Hadolint explanations. Problems arise where right-to-left prose wraps left-to-right command names, when a font makes characters difficult to distinguish or when a CMS inserts typographic punctuation into code.
Worked situation. A bilingual incident guide places a command next to an Arabic paragraph. The words are accurate, but punctuation visually moves and a copied flag loses its leading hyphen. The fix is code isolation, copy testing and visual inspection, not changing the semantic rule.
Common mistranslation. Treating a screenshot as proof of correct copy-and-paste behavior misses invisible Unicode and layout defects. Better interpretation. Keep code spans in an isolated direction, preserve ASCII command punctuation and test rendered text on mobile and desktop layouts.
A precise localization can be tested like a technical change. Preserve the English diagnostic alongside the target-language rendering in a review fixture. Check that identifiers, severity, references and actions remain traceable. Then hide the English sentence and ask a fluent target-language reader what the message authorizes and what it does not claim. A translation passes this exercise only when the reader reaches essentially the same practical interpretation. Elegant wording without that equivalence is not sufficient.
Reviewer exercise. Ask native-language reviewers to copy snippets, identify rule codes and report whether visual order matches logical token order. Then write a short answer explaining what the reader can safely do next. Make the answer refer to the file, the rule or the pipeline step rather than to a general fear of an error message. If you cannot tell what was checked, mark the translation incomplete; a polished sentence with a missing object is still misleading.
A complete example: from an English finding to a defensible localized explanation
Imagine a fictional project with a Dockerfile that uses a mutable-looking base-image reference, does not specify an intended non-root execution user, and installs packages without a clearly documented pinning strategy. The team runs Hadolint on that file during a pull request review. The output contains diagnostic IDs and severity labels. The translation assignment is not to rewrite the Dockerfile, nor to claim the image is compromised. It is to help a developer understand what the tool examined and how to decide whether each recommendation applies.
First, the writer records the source filename, Hadolint version, invoked command, active configuration and any relevant ignore settings. Next, the writer makes a two-column glossary: on the left are untranslatable tokens such as DL3006, FROM, WORKDIR and the actual repository path; on the right are human explanations of base-image references, working-directory instructions and rule severity. The glossary makes accidental alterations visible before the paragraphs are translated. Reviewers can search the original message by ID even if their interface language is different.
For each finding, the translated note follows the same order: observation, effect, proposed check, uncertainty. For example, ‘The base-image reference should be reviewed because the selected tagging pattern may not provide the team’s desired release control. Verify the approved image reference before changing the Dockerfile.’ This is more informative than ‘The image is dangerous.’ It also avoids promising that one pinning change makes the entire software supply chain safe.
The team then compares the translated advice against a harmless test revision. It runs the same linter settings on the old and new sample, records which diagnostic IDs changed, and checks that the CI result is explained correctly. A different reviewer reads the localized summary without the English source. If that reader can identify the same action and the same limits, the translation is ready to share. If not, the original report remains the reference while the wording is revised.
Professional glossary: words that change decisions
- lint: A static assessment of the written Dockerfile according to active rules, not an image-build certificate.
- Dockerfile: The build recipe whose instruction keywords must remain executable syntax.
- DL code: Hadolint’s rule identifier prefix; copy it exactly.
- SC code: ShellCheck diagnostic identifier for relevant shell-analysis findings.
- severity: The classification of a finding; distinguish it from exploit likelihood.
- failure threshold: The configured severity boundary used when setting a failing exit status.
- ignore: A selective suppression of a rule result, not remediation.
- trusted registry: A registry permitted under a particular lint policy, not a universal safety assurance.
- configuration: The file and flags controlling what is checked and reported.
- report artifact: A saved result that may be consumed automatically and should retain its schema.
- WORKDIR: A Dockerfile directive establishing a working-directory context in the image.
- RUN: A Dockerfile instruction executing a build-time command.
- USER: The instruction selecting the user for later steps and runtime defaults where applicable.
- nonzero exit: A process status used by automation; not an adjective to translate.
- Unicode QA: Validation of characters, display order, copying, accessibility and semantic equivalence.
Frequently asked questions
1. Should I translate the word FROM in a Dockerfile?
No. FROM is executable Dockerfile syntax. Translate the explanation of its purpose, not the instruction token. The same principle applies to RUN, WORKDIR, COPY and other Dockerfile keywords. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
2. Does a Hadolint success mean an image is secure?
No. A passing lint result means the active checks did not produce blocking results under the selected configuration. Build testing, package analysis, threat modeling and runtime validation answer different questions. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
3. Can I translate DL3006?
Translate the accompanying explanation, but never translate the identifier. DL3006 must remain searchable and must match its configured use in ignore lists and reports. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
4. Is a warning always a pipeline failure?
Not necessarily. Check the severity threshold, invocation outcome and the CI setup. A displayed finding can exist without being the reason for a failing exit code. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
5. May I translate a Dockerfile path shown in an example?
Only when intentionally creating a distinct, tested example. Otherwise preserve the real path. Localization of prose is not permission to alter repository data. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
6. Are inline ignores an accepted fix?
They can be a documented policy choice, but ignoring a rule does not correct the underlying condition. Record the scope, owner, rationale and review date where appropriate. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
7. How do I handle right-to-left language?
Keep command examples isolated in code spans or blocks with reliable directionality, inspect punctuation around embedded Latin identifiers and repeat copy-and-paste tests. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
8. Where should I confirm flags and rule behavior?
Check the exact Hadolint version and its upstream documentation. New options or default rules can change; the article is an educational guide rather than a release-specific replacement for upstream help. In a production translation, confirm the surrounding command, configuration and audience before adopting this short answer as a general rule.
Final review and further reading
A reliable Hadolint localization should withstand three independent checks: a technical reviewer can trace every rule ID and file reference to the unmodified source; a fluent reader understands the practical implication without making unsupported assumptions; and a copy test shows that code still behaves as intended. Keep the raw technical artifact separate from translated narrative. When a flag or default has changed between versions, make the version visible rather than forcing an old explanation onto a new output.
- Hadolint project documentation and rule reference — first source for actual commands, severities and config.
- The Gold Standard of Translation — broader principles of accurate, verifiable meaning.
- Syft CLI Localization — a separate guide to bill-of-materials outputs, not Dockerfile linting.
- OSV-Scanner CLI Localization — dependency advisory interpretation rather than Dockerfile rules.