Translate Like a Pro | 10400 — nerdctl CLI Localization: containerd Namespaces, Compose, BuildKit and Unicode QA

nerdctl CLI localization means writing trustworthy multilingual instructions for the containerd command-line environment without changing commands, namespaces or workload destinations. Translators who work with nerdctl run, nerdctl –namespace, nerdctl compose, image pulls, BuildKit builds and OCI archives need to distinguish natural-language explanations from executable syntax. A precise translation helps readers operate the correct containerd namespace and interpret results, while leaving all technical selectors intact.

This nerdctl translation guide is designed for international platform engineers, documentation teams, trainers and support desks. Although nerdctl deliberately resembles the Docker command line, it interacts with containerd and has its own capabilities and requirements. A namespace such as default or k8s.io is not merely a heading to translate: it is part of the execution context. Compose compatibility also needs careful wording, because some specification fields and features may behave differently from another implementation.

Readers will learn how to explain commands by effect, choose safe examples for rootless environments, validate image and container states, translate build and troubleshooting instructions and check Unicode text without tampering with parser keys. The following cases use fictional names and reversible lab operations where possible; verify namespace, installed version, daemon access, network plugins and BuildKit availability before executing them on a real host.

Main question: how can nerdctl command lines remain executable while the explanation becomes genuinely readable?
Reader: multilingual documentation writers, engineers, translators, technical trainers and support staff.
Workflow: inspect a safe sample, define intent, protect identifiers, explain action, test and publish.
Protection: never translate flags, schema keys, source or destination references, image digests or secret values.
Accuracy: distinguish observation, preparation, local state changes, remote transfers and destructive effects.
Quality: check shell quoting, Unicode normalization, screen readers, right-to-left direction and copied code.
Security: use fictional hosts and scrub credentials, internal hostnames and user data.
Release: verify each example on the intended tool version and keep an audit of the test context.

What nerdctl actually does and why the distinction matters

nerdctl offers a Docker-like interface to containerd, with support for container lifecycle commands, image handling, namespaces, Compose and optional build features. It is particularly important to distinguish a containerd namespace from a Kubernetes namespace. Translators must preserve both the command option and the object-selection context that determines what the operator will see or change.

Podman has its own container-management and rootless workflows, Buildah is an image-building specialist, and Skopeo moves images between storage backends and registries. This article covers the distinctive nerdctl-to-containerd operator model, especially namespace targeting, build dependencies and Compose behavior. It is not a general Kubernetes troubleshooting owner or a replacement for generic Docker CLI reference material.

A translation project often begins with an English source page that contains short commands, screenshots and occasional explanatory sentences. That page may seem complete to an experienced operator yet omit the assumptions beginners most need: which terminal is open, which account owns the object, which host is being changed and which output counts as evidence. A world-facing guide should restore these facts explicitly. Doing so is not a departure from faithful translation. It is the kind of accurate explanation that allows the same technical procedure to be understood across language communities without creating different operational instructions.

A second challenge is that names can look like ordinary words. A tool can have a command named run or copy; a registry or namespace may include a noun that happens to be translatable; a YAML key may look like an English phrase. The deciding question is whether another program expects exactly those bytes. When the answer is yes, keep the token literal and explain its role separately. When the answer is no, consider whether a local-language expression communicates the intended action more clearly. This distinction prevents both needless untranslated jargon and dangerous changes to technical interfaces.

Start with the five layers of a reliable technical translation

The operator’s intention

Write down who is acting and what they intend. An instruction about observing state needs different language from one about deleting or publishing it. Use verbs that make the effect unmistakable.

In practice, treat this layer as a separate review pass for nerdctl. Ask one person to inspect the command and its environment while another reads the translated explanation without advance knowledge. Compare the questions they believe the instruction answers. If they disagree about the object, scope or consequence, the article is not ready. Correct the ambiguity in the explanatory language first, then verify that every code sample still matches the approved source. A short, tested instruction is worth more than a longer untested paragraph.

The executable interface

Identify flags, paths, object names, filenames, registry references, namespaces, schema keys and digest strings. Keep these out of general prose editing, and protect their punctuation and casing.

The environment

Name operating system, runtime context, versions, permissions and network access. A command that works in one setup may produce different evidence elsewhere; that difference must not be disguised as a translation choice.

The evidence

State what observation would establish success, failure or partial progress. Keep raw diagnostic fields and exact timestamps available for operators even when their explanations are localized.

The reader’s next decision

End every risky example with an explicit next move: continue, verify, request authorization, choose a safer read-only command, or stop. Good documentation supports judgment instead of rewarding blind copying.

Safety checks before editing the first code block

Using default when the intended containerd namespace was k8s.io or another configured namespace
Claiming complete Docker Compose parity despite implementation-specific unsupported fields
Assuming BuildKit or CNI dependencies exist merely because nerdctl is installed
Accidentally exposing Kubernetes workload metadata when demonstrating logs
Treating image import into a namespace as a deployment of a Kubernetes resource

Treat example.invalid as an intentionally non-routable documentation domain. Never present it as a production registry or service. Use placeholders that clearly signal their illustrative purpose; if an example contains a token that must be replaced, identify precisely which token and require a destination check. In source control, store code snippets and their expected test results separately from translators’ comments. This allows automated checks to detect a changed quote mark, omitted option or altered path before the change reaches a public guide.

Do not infer safety from the fact that an operation is presented in a tutorial. Even a command that looks like an inventory query can reveal private labels or application metadata. Operations that push, delete, create resources or change configuration should be practiced only in a disposable environment. Screenshots and terminal transcripts deserve the same privacy treatment as exported data: mask tokens, internal addresses, personal names and content from real customer workloads. Readers can learn the technical principle without seeing someone else’s secrets.

Worked nerdctl examples: translate the meaning, preserve the command

The examples below progress from lower-risk observations to operations that can create or change state. Each case gives the intended purpose, a literal sample, the part that can be translated, the realistic mistake to avoid and an evidence check. Read the commands as teaching material, not as a batch script. Names and registry addresses are synthetic. For commands that require an existing working container or service, first create the object safely in a dedicated lab and substitute its actual name or ID.

1. Checking versions

Purpose. record the CLI and server information available to the operator. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl version

What remains literal. version values and component names. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: translate the significance of version compatibility. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. an outdated screenshot can imply an unsupported feature exists. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. compare installed versions with the guide’s tested environment. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, write a version note instead of changing command syntax. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

2. Inspecting the runtime

Before the command. learn which containerd and runtime configuration a command will use. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl info

Translation boundary. Preserve runtime names, storage keys and numeric values. The local-language sentence can clarify the real task: explain which facts affect a translated walkthrough. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. mistranslating a configuration key prevents accurate troubleshooting. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. compare sanitized info output from the target host. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, include prerequisites rather than guessing the missing component. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

3. Listing namespaces

Read the situation. see the containerd namespaces present before selecting objects. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl namespace ls

Literal and explanatory language. Treat namespace names including default and k8s.io as identifiers or execution syntax rather than ordinary words. A sound explanation will explain namespaces as selection contexts rather than natural-language labels. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. changing a namespace token can hide images and containers from view. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. check the selected namespace against a named test object. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, include an explicit namespace-selection instruction. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

4. Inspecting the default namespace

Operational setting. list containers in one chosen containerd namespace. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl --namespace default ps -a

Preserve the contract. The exact spelling of –namespace option, default value and ps flags belongs to the software-facing layer. What can be improved in another language is the explanation: translate which objects are included and whether exited containers appear. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. a user may conclude there are no containers because they inspected the wrong namespace. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. compare result with the intended test container list. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, repeat the namespace in every copied example where ambiguity matters. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

5. Inspecting Kubernetes-linked context

Purpose. observe containers in the containerd namespace often used by Kubernetes. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl --namespace k8s.io ps -a

What remains literal. literal k8s.io token and container identifiers. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: explain the distinction between containerd namespace and Kubernetes API namespace. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. users might mistake this command for kubectl and expect cluster-wide visibility. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. compare with approved Kubernetes inventory only in a lab. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, state that this tool does not replace the Kubernetes control plane. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

6. Listing images in a namespace

Before the command. show stored images in a selected containerd context. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl --namespace default images

Translation boundary. Preserve namespace, repository, tags and image identifiers. The local-language sentence can clarify the real task: explain why an image may exist in one namespace and not another. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. a translation can wrongly call missing local image a registry failure. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. compare inventories under two intentional namespaces. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, avoid suggesting an immediate pull until context is verified. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

7. Pulling an image

Read the situation. retrieve a named image into the current namespace. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl pull docker.io/library/alpine:latest

Literal and explanatory language. Treat registry hostname, repository and tag as identifiers or execution syntax rather than ordinary words. A sound explanation will explain the difference between fetching and running. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. a mutable tag may give different image content across dates. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. record image digest or ID after the pull. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, pin references where reproducibility matters. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

8. Running a disposable container

Operational setting. start a short-lived process in an isolated lab container. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl run --rm docker.io/library/alpine:latest echo ready

Preserve the contract. The exact spelling of run, –rm, image selector and command arguments belongs to the software-facing layer. What can be improved in another language is the explanation: explain process execution and automatic cleanup. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. a translated caption may falsely imply durable application storage. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. observe successful exit and absence of the container afterwards. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, direct persistent workloads to a separate volume and lifecycle discussion. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

9. Naming a container

Purpose. start a named example service in detached mode. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl run --name demo-web -d docker.io/library/nginx:alpine

What remains literal. –name, -d, image reference and publish settings if any. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: explain that detached execution does not guarantee external network reachability. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. readers may expect a public endpoint without a port mapping. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. check ps and local network configuration after launch. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, add a separate approved port-publishing instruction. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

10. Listing all containers

Before the command. interpret running and exited containers in the selected namespace. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl ps -a

Translation boundary. Preserve container IDs, state values and columns. The local-language sentence can clarify the real task: translate operational meaning rather than object identifiers. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. confusing exited with deleted can send users to the wrong repair. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. compare lifecycle states from a controlled run-stop exercise. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, provide a short state glossary. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

11. Viewing application logs

Read the situation. read the output stream of a named container. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl logs demo-web

Literal and explanatory language. Treat container selector and application-emitted error codes as identifiers or execution syntax rather than ordinary words. A sound explanation will explain where logs originate and why redaction matters. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. unredacted logs may carry tokens, URLs or personal data. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. compare a sanitized sample with the actual lab output. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, retain message order and timestamps during translation. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

12. Executing in a container

Operational setting. perform a read-only diagnostic in a running example container. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl exec demo-web id

Preserve the contract. The exact spelling of exec, object selector and the id command belongs to the software-facing layer. What can be improved in another language is the explanation: explain container user context separately from host identity. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. a translator may describe exec as changing host permissions. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. verify UID output in a disposable container. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, warn readers not to infer broad privilege from one diagnostic. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

13. Stopping a container

Purpose. request termination of a selected example workload. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl stop demo-web

What remains literal. stop and literal container name. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: distinguish stopping execution from removing the object. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. a guide may suggest data vanished when only the process ended. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. check container state before and after the operation. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, note potential supervisor or orchestrator restart behavior. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

14. Removing a container

Before the command. delete an expendable stopped container object. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl rm demo-web

Translation boundary. Preserve rm and exact container selector. The local-language sentence can clarify the real task: explain potential loss of writable-layer state. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. a softened verb like hide is unsafe for a destructive cleanup. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. confirm volumes and backups before using the command. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, prefer inspection when state is uncertain. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

15. Listing local networks

Read the situation. discover network definitions available to containers. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl network ls

Literal and explanatory language. Treat network names, drivers and IDs as identifiers or execution syntax rather than ordinary words. A sound explanation will translate connectivity consequences without renaming the objects. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. local bridge networks should not be described as public internet access. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. cross-check one test container’s network attachment. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, add platform and plugin prerequisites to the guide. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

16. Listing volumes

Operational setting. inventory named persistent storage objects. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl volume ls

Preserve the contract. The exact spelling of volume names and storage-driver data belongs to the software-facing layer. What can be improved in another language is the explanation: explain volume lifecycle separately from container lifecycle. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. a translated cleanup sentence may tell users to delete needed data. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. check volume ownership and backup plans before cleanup. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, use list commands as the default diagnostic path. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

17. Building with BuildKit

Purpose. build an image from a local Dockerfile or compatible build instructions. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl build -t demo-app:lab .

What remains literal. build, -t, tag and trailing context dot. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: explain the requirement for available BuildKit service in many setups. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. a guide can incorrectly blame translation when the build engine is not running. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. verify BuildKit configuration with a minimal test project. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, document optional dependency checks before the command. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

18. Starting a Compose project

Before the command. start services described by a reviewed Compose file. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl compose up -d

Translation boundary. Preserve compose, up, -d and YAML schema keys. The local-language sentence can clarify the real task: explain that starting services changes runtime state. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. saying all Docker Compose features are interchangeable overpromises compatibility. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. test only a small Compose sample using supported fields. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, link to implementation-specific limitations. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

19. Inspecting Compose behavior

Read the situation. view the state of services in a Compose project. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl compose ps

Literal and explanatory language. Treat project selection, service names and status information as identifiers or execution syntax rather than ordinary words. A sound explanation will explain how Compose groups containers for people. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. a translation that renames service keys may break dependencies. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. compare the output with the names in the unchanged YAML. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, keep service identifiers in code and gloss them in prose. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

20. Reading Compose logs

Operational setting. collect application messages across services in the active Compose project. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl compose logs

Preserve the contract. The exact spelling of service names, timestamps and log ordering belongs to the software-facing layer. What can be improved in another language is the explanation: tell readers how to attribute a message to a service. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. translating log lines can erase the original error text needed for search. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. compare source logs with sanitized translated summaries. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, retain key errors and explain rather than overwrite them. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

21. Stopping a Compose project

Purpose. stop and remove project resources according to Compose behavior. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl compose down

What remains literal. down verb and project context. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: explain what may remain, including separately managed data. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. an overly reassuring translation may imply no persistence consequences. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. inspect project state and volume policy first. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, offer a stop-only discussion when removal is not approved. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

22. Saving an image archive

Before the command. export a local image for controlled transfer. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl save -o demo-app.tar demo-app:lab

Translation boundary. Preserve output path, archive format and exact image reference. The local-language sentence can clarify the real task: describe packaging rather than running or publishing. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. renaming an archive in translated prose can break the later import sequence. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. verify archive existence and hash in the test workspace. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, record transfer destination separately. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

23. Loading an image archive

Read the situation. import an image archive into current containerd context. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl load -i demo-app.tar

Literal and explanatory language. Treat archive path and selected namespace as identifiers or execution syntax rather than ordinary words. A sound explanation will explain that import creates availability, not running containers. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. the wrong namespace can make a successful import appear missing. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. inspect image inventory immediately after loading. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, state target namespace before the import command. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

24. Tagging an image

Operational setting. give a local image a second reference. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl tag demo-app:lab registry.example.invalid/team/demo-app:test

Preserve the contract. The exact spelling of both image references, registry and tag tokens belongs to the software-facing layer. What can be improved in another language is the explanation: explain that local tag assignment is not upload. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. an unreviewed registry path can point to the wrong release destination. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. compare image IDs under both local names. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, require separate destination approval for push. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

25. Pushing an image

Purpose. upload a reviewed artifact to an authorized registry. This is a useful point in the nerdctl workflow to stop and ask what a novice actually needs to decide. The command is not a sentence to be translated word by word: it is an instruction interpreted by software. Describe the prerequisite, the intended observation or state change, and the scope of the target. When a reader can explain those three facts before copying anything, the multilingual guide becomes instruction rather than decoration.

nerdctl push registry.example.invalid/team/demo-app:test

What remains literal. registry address and exact image reference. Keep these tokens byte-for-byte where they are machine-consumed. Translate the human explanation instead: explain transfer, credentials and possible public visibility. If the example uses a fictional host or object, identify it explicitly and tell the reader to substitute only an authorized real value. Do not translate a placeholder into a genuine target without a separate review. Users often copy code blocks directly; visual elegance must never take precedence over executable correctness.

Failure to watch for. a translated phrase could obscure the fact that bytes leave the host. The harm is not merely an awkward sentence. It may send a reader to another environment, give a false picture of what changed, conceal a missing permission, or create misleading evidence in a ticket. Ask a reviewer to paraphrase the action without looking at the command. If that paraphrase disagrees with the software’s actual effect, revise the prose before publication.

Verification. test on a private training registry and compare digests. This is the evidence the translated guide should ask a reader to collect, rather than a vague success claim. Record only permitted, non-sensitive fields; preserve timestamps, identifiers and numeric values when they matter. If the evidence does not match, confirm authorization before production publication. The important teaching principle is to let the evidence change the explanation, not to edit the evidence until it resembles the intended result.

26. Inspecting a container

Before the command. read structured container configuration and runtime metadata. Put that purpose ahead of the syntax so the reader understands what the example is trying to accomplish. Readers may arrive from troubleshooting tickets, videos, or translated interface screenshots; they may not share the writer’s assumptions. Establish the target machine or registry, the permissions needed, and whether the action observes, creates, transfers, or deletes an object. A technically correct command attached to an inaccurate purpose is still poor documentation.

nerdctl container inspect demo-web

Translation boundary. Preserve JSON property names, identifiers and serialized values. The local-language sentence can clarify the real task: explain relevant settings without altering the raw record. Make a two-column editorial note listing protected syntax on one side and translatable captions on the other. This works especially well when translators do not have access to the development environment. It prevents a well-intentioned proofreader from changing a command merely to make a passage grammatically consistent.

Likely misunderstanding. exposing environment values in translated screenshots can leak secrets. In support work, a seemingly small ambiguity can compound: the reader repeats the wrong action, collects irrelevant logs, and reports a failure that is really an instruction error. Use exact nouns for the affected object and explicit verbs for observation, mutation and deletion. Avoid terms such as fixed, deployed or synchronized until the next test actually proves that outcome.

Review procedure. redact selectively and compare schema keys with the source. Have an operator carry out that check in a disposable environment using the exact command block printed in the translated article. A translator can then compare the observed result with the explanation sentence by sentence. When the expected condition is absent, publish only fields needed for the lesson. Keep a small record of the tested version and context so a future editor can distinguish software change from translation error.

27. Reviewing system cleanup

Read the situation. identify a potentially destructive cleanup action. A translator should first determine the expected state before and after this step. Describe the ordinary-language intention in terms of objects and observable outcomes, not merely by naming a subcommand. This enables a reader to notice a mismatch between a local environment and the published example. The practical question is not whether the vocabulary sounds polished, but whether someone following the translated instructions will make the same safe decision as someone using the source language.

nerdctl system prune

Literal and explanatory language. Treat prune verb and the targeted containerd context as identifiers or execution syntax rather than ordinary words. A sound explanation will explain deletion scope and warn against casual execution. The best translated instruction may be longer than the original because it must explain a distinction the source author assumed. That is acceptable. Leave code in a monospaced block, and translate the surrounding paragraph, labels for the reader and carefully chosen warnings.

Where accuracy fails. a translated shortcut could remove cached or stopped resources needed for recovery. This is why language review alone is insufficient for a command-line guide. Someone familiar with the tool should examine not only grammar, but the implied scope of the command and the next operational decision. When danger depends on a small qualifier, place the qualifier before the example rather than burying it in a note after the code block.

Acceptable evidence. review disk and object inventories in a lab before any action. The reader needs to know which output is decisive and which output is merely incidental. A zero exit status may prove a command finished, but it cannot always establish that a service is healthy or an artifact was published to the intended place. If that distinction matters, keep the command in a cautionary box rather than a default step. Translate the interpretation while preserving the raw observations that another engineer might need to audit.

28. Handling rootless environments

Operational setting. evaluate whether the intended rootless containerd configuration is present. In an international team, commands often travel without the surrounding assumptions: a colleague forwards a snippet, a support agent quotes a screenshot, or a translator receives only one paragraph of a longer runbook. Restore that context. State the intended environment and the role of the action before displaying the command. Clear explanation reduces the chance that a reader will apply a valid command to an invalid or unsafe target.

nerdctl info

Preserve the contract. The exact spelling of runtime settings and user identity information belongs to the software-facing layer. What can be improved in another language is the explanation: translate setup constraints without promising a universal one-line installation. Keep command examples stable across editions wherever possible, because consistency simplifies testing and support. If a local environment genuinely requires a different path or hostname, document it as a controlled adaptation rather than silently presenting it as a translation.

Counterexample. assuming a system service and rootless instance share state creates misleading directions. A translation that sounds smoother may nonetheless be wrong if it changes who owns an object, what destination receives data, or whether the action was read-only. Invite a second reviewer to identify the most plausible wrong interpretation, then make that interpretation impossible with a short plain-language sentence. That test is more valuable than polishing synonyms.

How to close the loop. test commands under the target account with approved permissions. Use this check to evaluate the translation as an instruction, not just as a written paragraph. The reviewer should be able to match every promised effect with observable evidence. If an unexpected result appears, document the correct runtime socket and prerequisites for that platform. An effective multilingual manual therefore teaches a method of diagnosis, including when to stop, rather than a brittle sequence of commands to copy blindly.

A glossary that keeps technical nouns and user language apart

containerd namespace: storage and object context in containerd, not a Kubernetes Namespace API object
nerdctl versus Docker: familiar syntax with different underlying runtime integration
Compose project: a set of related services and their configuration
BuildKit: a build engine often required for nerdctl build, depending on installation
image archive: transferable bytes, distinct from a running container
rootless execution: privilege model requiring its own setup and tests

A glossary is useful only when it controls actual misunderstandings. It should not become a list of untranslated English terms without explanation. For each entry, record the invariant token, the concept explained in natural language, one example of correct use and the most likely misunderstanding. Ask language reviewers to check whether the term still means the same thing inside a warning, a tutorial heading and a support conversation. Words such as image, instance, root, manifest and namespace are especially dependent on context; a single dictionary equivalent will often be too blunt.

An end-to-end translation and QA workflow

1. Capture the tested source

Save the original commands and record the tool version, operating system, runtime context and documentation date. Copy the exact code bytes rather than recreating them from screenshots.

The key question for this stage is whether a reader in another country can reach the same conclusion without gaining a different execution contract. Keep a small decision record when you intentionally leave a term untranslated, when a regional version needs separate prerequisites, or when a warning must be stronger than a literal translation. That record prevents a later editor from mistaking careful technical restraint for unfinished localization.

2. Classify each token

Mark flags and identifiers as protected, human-facing explanation as translatable, and environment-dependent values as replaceable only after review. This makes responsibilities visible to both translators and engineers.

3. Write the intended outcome

For every example, state which object is observed or modified, which prerequisites matter and what success or failure would look like. Translate that outcome before attempting stylistic polish.

4. Localize the instructional sequence

Use short paragraphs that put prerequisites before commands and evidence checks after them. Keep related warnings beside the step that creates the risk, not at the end of the article.

5. Test literal commands

Run the code blocks in a disposable environment with synthetic images, files and identities. A technical reviewer should compare the source and localized versions for exact syntax and practical outcome.

6. Test international text

Use accented Latin characters, CJK characters, combining marks and right-to-left text in purely human-facing strings. Check Unicode normalization, copying, code font rendering, terminal width and accessibility.

7. Review security and privacy

Remove passwords, tokens, internal hostnames, customer identifiers and unapproved log fragments. Check that a command is not unintentionally destructive and that example.invalid placeholders remain fictional.

8. Publish with traceability

Record who verified meaning, code, platform behavior and language clarity. Include official documentation links, the tested version and a revision note when syntax changes. Update examples only after another technical test.

Unicode, typography and cross-platform verification

Accents and composed characters

Compare text written with precomposed and combining forms. A display difference may not matter in prose, but it matters if someone copies the characters into a path or exact-match selector. Avoid giving localized filenames as if every host accepts the same normalization.

A robust test uses a small synthetic corpus and expected outcomes recorded before the translation begins. Include one plain-English display message, one non-ASCII user-facing message, a path or image name that must not change, a structured record, and an error that requires stopping. Review the rendered article and a plain-text copy of its code blocks. If the prose looks correct but copying a command breaks it, the edition has failed a fundamental accessibility and correctness test.

CJK and full-width punctuation

Check line wrapping and the width of monospace terminals. Do not replace ASCII quotes, dashes, slashes or colons inside commands with typographic variants that can change parsing. An explanation can use native punctuation while the executable example remains literal.

Right-to-left languages

Keep command blocks isolated in left-to-right direction so identifiers and punctuation stay in their executable order. Surround the block with properly translated explanation and verify that screen readers announce a coherent sequence.

Shell quoting

Do not assume Bash, PowerShell and Windows command shells handle quotation or environment variables identically. Provide platform-specific examples when needed rather than presenting a translated command as universally portable.

Machine-readable output

Preserve JSON keys, YAML structures, digests and numeric codes exactly. If you translate a diagnostic table, label the commentary as a human summary and retain a way to see the original data. Avoid silently editing the source evidence.

Inclusive reader testing

Ask a beginner to predict the command’s consequence and an experienced operator to check the syntax. Invite reviewers using different display sizes and assistive technology. A high-quality localization must be readable as well as technically valid.

Questions readers ask about translating nerdctl guides

Should the command verbs themselves be translated?

No. The CLI parser expects fixed syntax. Translate what the command does, the prerequisites, the cautions and the interpretation. A separately localized application interface is a different engineering project that must be implemented and tested by the software maintainers.

For nerdctl, the practical test remains the same: keep the machine-facing instruction identical, check the intended object and scope, and make the human-facing explanation accurate enough for a novice to identify both the safe next step and the conditions under which they should stop.

Is a successful exit status proof that the reader achieved the whole goal?

Not always. The process may have succeeded at a narrow step without proving deployment, network reachability, transfer integrity or security. Ask for evidence at the level of the claim; describe incomplete work as incomplete.

How should examples use filenames or image references in other languages?

Keep executable examples stable unless the file is explicitly part of a tested multilingual scenario. If a name is a placeholder, explain the replacement rules and whether the environment permits Unicode. Never change a digest or identifier just to make a page look localized.

What if the tool prints English errors?

Quote only sanitized, necessary parts exactly, then provide an accessible translation and explanation next to them. Users need the original error code and searchable terms, especially when official support resources use those identifiers.

Can screenshots replace code blocks?

No. Images help show context but do not provide reliable copyable syntax or screen-reader access. Include tested text commands, alt text when images are used, and an explanation that survives changes in interface layout.

How do we handle commands that can delete or publish content?

Lead with the consequence and the target, require an authorized test environment, and offer a read-only verification step before action. Never make a risky instruction sound harmless by choosing a softer translated verb.

Should each language use different examples?

The same sanitized example across languages is usually easiest to test. Where local operating systems or shells require changes, document them as platform adaptations with separate tests rather than silently changing the source example.

How often should this guide be checked?

Recheck when the relevant tool version, command help, platform packaging or registry policy changes, and whenever a reader reports a reproducible mismatch. Record the exact tested environment rather than claiming permanent compatibility.

A final release checklist

All examples have an explicit purpose, tested context and outcome.
Code spelling, command separators, flags, resource names and schema keys survived translation.
Any read-only claim, state-changing claim or destructive warning matches observed behavior.
Sample output is redacted and translated explanations do not replace raw evidence.
Registry and filesystem destinations have been reviewed independently.
Unicode, right-to-left rendering, copy/paste and assistive reading have been checked.
An owner, a tested tool version and an approved source are identifiable.
Readers know how to stop and investigate an unexpected result.

The best technical translation does more than help readers decode a foreign-language sentence. It helps them make the right decision with the same executable contract. Keep the explanation generous, the code precise, the evidence reviewable and the safety boundary unmistakable. For reference, consult the official nerdctl project documentation and the related upstream guide. For an adjacent topic in the wider translation library, see the connected technical translation article. Those references are aids to verification; they do not replace testing the commands in the environment the reader actually uses.