Earthly CLI localization means translating the human guidance around Earthfiles, build targets, reproducible container steps, artifacts and image publication without changing executable syntax. This world-facing guide explains how to translate Earthly build instructions, interpret earthly +target, distinguish SAVE ARTIFACT from SAVE IMAGE, and review multilingual output in a way that developers can safely follow across countries, shells and teams.
Readers looking for how to translate an Earthfile, localize Earthly CLI commands, explain Earthly caching, troubleshoot a failed target, or translate CI build logs need more than a bilingual vocabulary table. The important question is what a command actually does: where the source comes from, which target runs, what leaves the build environment, and whether an artifact has merely been built, exported locally or pushed remotely.
Earthly has versioned documentation, and command options can evolve. Treat the installed earthly –help and the appropriate official reference as the authority for supported flags. Keep Earthfile keywords, target names, artifact paths and registry references exactly as supplied; translate explanations, warnings and reader-facing messages instead. The practical examples below are teaching examples and are not instructions to publish an image from an unverified project.
Quick checklist before translating an Earthly guide
- Record the installed Earthly version, OS, shell and Earthfile path.
- Identify the exact +target, its dependencies, build arguments and expected outputs.
- Keep Earthfile instruction keywords, file paths, target references, image tags and registry names literal.
- Say whether an artifact is saved inside the build graph, exported to the host or pushed to a registry.
- Explain cache reuse as a performance behaviour, not proof of fresh execution.
- Test copy-and-paste, Unicode filenames, log wrapping and right-to-left display with harmless inputs.
- Review CI permissions, secret handling and network publication separately from language quality.
Understand the build graph before translating any command
An Earthfile defines named targets and steps that Earthly executes through a build environment. Think of a target as a reproducible recipe with declared inputs and outputs. Translating the word ‘build’ without identifying its input files and destination leaves readers uncertain about whether anything has been copied, compiled, saved or uploaded. The sections below follow a source repository through target resolution, execution, extraction, caching and delivery.
1. The Earthfile is not a prose document
An Earthfile uses special instructions and structured syntax to describe build stages. Keywords such as FROM, WORKDIR, COPY, RUN and SAVE ARTIFACT are instructions rather than ordinary English sentences; their spelling is part of how the file is parsed. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A translator receives an Earthfile and a README in the same folder. The README can explain the purpose of each stage in another language, but the machine-readable file must remain valid for the tool that runs it. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Replacing FROM with an equivalent natural-language verb makes the configuration unreadable. Replacing a path with a translated phrase can direct a COPY instruction toward a nonexistent file. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Keep executable statements intact. Add human explanations beside examples and validate the actual Earthfile with the relevant installed release. Ask an engineer which comments are safe to localize. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
2. Targets are named entry points
Earthly names its build recipes as targets. A reference such as +build identifies a target, and the leading plus sign has syntactic meaning. A target can depend on other targets and therefore cause more work than its short name suggests. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
An onboarding guide tells a colleague to run earthly +test. The reader needs to know whether +test depends on +build and whether either step touches the network or produces an artifact. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Turning +test into an equivalent word in another language changes the identifier; merely translating the explanatory label is fine. Describing all targets as applications is also misleading. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Show the exact target token inside code and a separate translated description outside it. State which dependencies run, what success means and which outputs should be checked. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
3. Working directory and build context
The active working directory and the Earthfile’s location influence which files enter the build context. Inside a target, WORKDIR changes the directory used by later commands; it is not a command to rename a project. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A developer follows a translated tutorial from a parent directory and discovers that a relative path in COPY points at the wrong place. The error is about context rather than language fluency. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
The phrase ‘project folder’ can be too vague: it might mean the repository root, the Earthfile directory or a directory inside the container. A wrong translation obscures this distinction. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Name the relevant directory in each step. When providing a path example, specify which shell and operating system it assumes, and use a harmless sample tree to validate the relative path. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
4. The meaning of FROM
FROM chooses a starting environment, which may be a container image or another referenced build target. It determines the execution context for subsequent instructions and can bring a toolchain into scope. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A translated recipe starts FROM a language runtime image. A newcomer mistakes the image reference for the output image and assumes that the final application has already been published. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A base image is not a finished release artifact. A tag is not an assurance of immutability, and a sentence that equates ‘using a base’ with ‘deploying a service’ may cause confusion. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Keep the exact image reference and explain the distinction between parent environment, build result and published image. Where reproducibility matters, discuss pinned versions or digests. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
5. COPY and source provenance
COPY transfers declared files into a build environment. The source and destination names are technical addresses, and case sensitivity can matter when a team works on different file systems. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A multilingual guide shows copying package metadata before copying application source. An engineer wants to understand why the two steps are separated and which files are available for dependency installation. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Changing file names, punctuation or case while translating a code sample may break the build. Calling COPY a move also suggests the original file disappears, which is not its intended meaning. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Describe the before-and-after locations explicitly. Test the example with sample files, avoid private paths, and show the command unchanged even when the filename looks like an English word. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
6. RUN describes work inside a build step
RUN invokes a command as part of the build. Its effect depends on the preceding filesystem state, environment and image, and the command may create files that subsequent stages consume. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A pipeline uses RUN to install dependencies and run tests. A translated guide should state whether tests execute during image preparation or after a deployed service starts. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A wording like ‘run the app online’ collapses a build-time command into a runtime service. A green exit code from a test stage does not prove the image was exported or deployed. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Identify the command’s current environment and expected exit status. Explain where logs appear, where generated files go and how to recognize a failure without encouraging blind retries. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
7. SAVE ARTIFACT and output identity
SAVE ARTIFACT records a file or directory as a build artifact that another target or a caller can refer to. That is different from saving a final container image, exporting a file to the host, or distributing a file to users. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A team builds a binary in one target and consumes it from another. The translated handover must say whether the binary is internal to the build graph or has been explicitly retrieved. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Calling every SAVE ARTIFACT action an upload can falsely promise that colleagues can download a file from a website. The artifact can exist without a public delivery step. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Use the words artifact, internal reference and host export with care. Point to the output path and ask the reader to verify the specific file at the intended destination. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
8. Artifact references use exact syntax
A reference such as +build/output.bin means an artifact path associated with a target; a separate retrieval action may be necessary to place it on the host. The prefix and slash are meaningful characters. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A localization reviewer sees a screenshot caption containing an artifact reference. The surrounding prose needs translation, but the code-like reference is an address within the build graph. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Removing the plus sign or replacing a slash with localized punctuation changes the target reference. A right-to-left display may visually reorder tokens even when stored bytes are intact. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Place exact references in code formatting. Compare copied bytes, not only appearance, and confirm the artifact exists in the selected target before telling readers where to find it. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
9. SAVE IMAGE is not SAVE ARTIFACT
SAVE IMAGE identifies a container image output. Image publication depends on configuration and invocation; building an image does not automatically mean a registry holds that image. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A tutorial generates an image for staging. One translator uses ‘publish’ for every occurrence of SAVE IMAGE, while the original workflow only saves an image locally. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
If someone later uses the translated tutorial as a release checklist, they may believe an image is available to deployment systems when no push occurred. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Differentiate image creation, local availability and registry publication. Require evidence such as an expected image reference or registry digest before describing the release as delivered. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
10. The difference between –push and local output
Earthly distinguishes normal builds from actions that publish outputs when appropriately configured and invoked. A push can have remote effects and should never be hidden inside casual instructions. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A continuous integration job runs a build for pull requests and adds publishing behaviour on a protected release branch. The text must identify which trigger can write to a registry. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
The sentence ‘run the build’ is insufficient if the included command has a publication flag. An automated reader could copy it into the wrong branch or personal environment. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Mark remote side effects in the first sentence of the step. Keep registry credentials out of examples and give a non-publishing alternative for learning or review. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
11. Images, registries and tags
Image names often contain registry hosts, repository names and tags. These fields may resemble natural words, but they are machine addresses that bind build results to deployment systems. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A user reads an international runbook containing registry.example.invalid/team/app:review. The .invalid address is intentionally illustrative, but its structure shows what must stay exact. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Translating a repository path or tag changes which image is referenced. Treating a mutable tag as an immutable fingerprint can also hide a provenance problem. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Use example.invalid for explanatory addresses, preserve delimiters and explain how a registry digest or verified metadata can establish the actual image identity. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
12. Build arguments are typed inputs in practice
Build arguments let callers vary a target’s behaviour while retaining the Earthfile structure. Their expected names, values and defaults must be checked against the specific target definition. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A multilingual setup note has a build argument selecting a test mode. One reader sets an argument to a translated word even though the target expects a particular literal value. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A pleasant translation may silently invert an option such as true and false or substitute a different environment name. Those are behavioural changes, not stylistic improvements. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Keep argument keys literal. Clearly distinguish example values that may be replaced from enumerated values that may not. Demonstrate safe values in a non-production build. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
13. Dependencies and target graph
A target can reference another target or its artifacts, creating a graph of work. Earthly may reuse computed results; that does not mean every dependency is freshly executed on each invocation. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A release engineer asks why an invocation of +package also produces a compiled binary. A good translation explains the relationship rather than listing commands without context. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Describing each target as fully independent hides implicit prerequisites. The reader may try to call a later stage without the source or configuration it needs. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Sketch the sequence with target names and expected inputs. Explain which results are inherited and which are new, then confirm behaviour using the build output and declared target graph. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
14. Caching is optimization, not assurance
Build caching can reuse prior work based on inputs and cache configuration. It improves speed, but a cache hit is not evidence that a new test ran or that a newly patched dependency was installed. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A team compares an initial slow build with a fast rerun. A translated report calls the second run ‘fully retested’ even though some stages may have been reused. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
That claim changes the assurance level and can mislead auditors. Cache output can also contain information that requires access controls, depending on what entered a layer. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Explain which steps were reused and which executed. If freshness matters, state the chosen cache policy and test it deliberately rather than assuming every successful build is new. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
15. Remote cache addresses and access
A remote cache can move reusable build results between machines or pipelines. Its registry reference, authentication boundary and retention policy belong to operational configuration. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A team wants faster builds across regions, but its cache may include intermediate code or dependencies. The localized guide must not describe a shared cache as a public mirror. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
An imprecise ‘sync cache everywhere’ instruction may expose proprietary artifacts or confuse an intermediate cache with the final deliverable. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Identify who may write and read the remote cache. Keep cache endpoints exact and explain that access review is separate from whether the text renders correctly. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
16. BuildKit’s operational role
Earthly commonly uses BuildKit as a build engine. This means diagnostics can involve engine connectivity, resources and execution logs in addition to Earthfile syntax. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A user encounters a failure before any target instructions run. A translated support article should distinguish inability to contact the builder from a compilation error inside a target. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Calling every failure a source-code bug wastes investigation time. It can also encourage someone to change application code when the actual problem is infrastructure access. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Start diagnosis with the observed failure stage. Record version, engine mode and a redacted error, then separate environment checks from target logic checks. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
17. CI mode and reproducibility claims
CI-oriented invocations can enforce stricter assumptions than casual local experiments. Local-only behaviour or dependence on a developer’s machine may become a problem in an automated pipeline. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A target works on a laptop because it relies on a local file or host behaviour. A translated release guide describes it as reproducible without testing it in CI. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
The word reproducible is a measurable claim, not a synonym for ‘worked once.’ Builds can also vary when external dependencies or unpinned inputs change. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Show the tested context, pin important inputs where possible, and distinguish convenience during local development from a build that can run predictably in the intended CI environment. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
18. Secrets must remain secrets
Credentials used to fetch dependencies or publish images should not be embedded in public Earthfiles, copied into logs, or included as literal sample values. A secret’s identifier is distinct from its value. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A translator is given a failed CI log containing a token alongside a registry authentication error. The error narrative can be translated without repeating the sensitive text. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Publishing the original log in a tutorial risks credential disclosure. Masking all context, however, can make a diagnosis impossible if it removes names of failing steps and statuses. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Replace values with conspicuous placeholders, keep non-sensitive command context, and recommend revocation or rotation if genuine secrets have already appeared in a public location. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
19. Error output: status before style
Build logs combine human text, status markers, file paths and tool output. Some messages are suitable for translation; others are evidence that must be copied exactly to diagnose a failure. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A remote teammate reports that an install command failed with a package manager error. The support guide should identify which target failed and which command emitted the line. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A free paraphrase that turns a dependency-resolution failure into a network failure sends readers down the wrong recovery path. A localized message must preserve uncertainty. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Quote a short redacted original error if permitted, add a plain-language explanation, and explicitly separate observed facts from proposed causes and next checks. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
20. Exit codes and failing stages
Process exit status and target failure determine whether an invocation succeeded as defined by that command. A zero result only covers the conditions actually checked. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A continuous integration dashboard marks a job green after an artifact target finishes. Another job is still responsible for signing and publishing the image. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Translating green as ‘secure and ready for production’ overstates the evidence. It can create a false security guarantee and obscure an incomplete release process. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
List stage-level completion criteria. Explain whether tests ran, outputs were generated, remote publication occurred and any independent runtime checks passed. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
21. Multiplatform builds and architecture names
Container images may target architectures such as linux/amd64 or linux/arm64. These are technical platform identifiers, not words to translate or visual design labels. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A release document mentions that a target produces an image for ARM hardware. A reader on a different machine needs to know the intended architecture and any builder limitations. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Replacing platform identifiers with broad phrases such as ‘mobile version’ changes meaning. Architecture mismatches may not be visible until deployment. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Keep platform strings literal and identify where cross-platform behaviour was tested. Verify the image metadata rather than inferring compatibility from the development laptop. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
22. Paths with accented and non-Latin characters
Source repositories can include filenames with diacritics, CJK characters or combining marks. The file system, shell and build environment may not all treat those forms identically. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A team has documentation files named with accented characters and tests an Earthfile under Linux after authoring it on another operating system. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A filename that looks identical can have different Unicode normalization. Copying from a richly formatted page can also introduce curly quotes or invisible characters. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Use UTF-8 consistently, test exact paths with controlled sample files and validate copied text at the byte level when a path unexpectedly fails. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
23. Bidirectional text and terminal safety
Arabic and Hebrew explanations can appear beside left-to-right target names and shell flags. Bidirectional rendering changes visual ordering without necessarily changing the underlying bytes. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A user copies +build/output.tar from a localized page. The displayed punctuation looks reversed because the line mixes writing directions. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A reviewer may ‘fix’ the text by inserting characters into the executable token, creating a new error. Visual legibility and machine equality require separate checks. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Isolate command text in code blocks, keep literal ASCII syntax and compare the actual pasted command in a safe shell. Avoid hidden directional formatting inside tokens. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
24. Quoting differs across shells
Shell quoting, variable expansion and path escaping vary between Bash, PowerShell and other command interpreters. The translated sentence cannot guarantee that one shell example works everywhere. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A beginner on Windows follows an example written for Bash. A translated guide makes it sound operating-system-neutral while retaining shell-specific syntax. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Translating quote marks into typographic punctuation can cause parsing errors. Explaining a Bash variable as a PowerShell variable can send the wrong value. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Label examples by shell, show only the syntax validated for that shell, and offer conceptual guidance for other environments rather than pretending commands are universal. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
25. Log timestamps and time zones
A build report may contain UTC times, local timestamps and durations. These serve different purposes: a timestamp anchors an event while a duration measures elapsed work. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A distributed team tries to correlate an Earthly failure with an artifact storage alert. One report uses local time and the other uses UTC. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Rewriting 02:00 UTC as 02:00 local without an offset changes when the event happened. Durations must never be converted into clock times. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Preserve the original timestamp and offset in technical evidence. If a localized display is useful, show the converted time separately and label the target time zone. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
26. Diagnostics should preserve causality
Different errors can arise from missing source files, a failed RUN command, unavailable registry access or an engine problem. The first observable failing stage is essential. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A reader sees a failing target during a multilingual workshop and asks for the ‘one fix’ that works for all environments. The instructor must resist oversimplification. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Copying a solution from an unrelated failure can alter cache settings or credentials without addressing the real cause. Friendly but vague language hides investigative work. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Use a small decision tree: resolve target, inspect context, read failing step, check connectivity where relevant, and rerun a harmless check only after recording the initial state. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
27. Releases require separate verification
An image or artifact produced by Earthly can be one input to a release process, but downstream scanning, signing, promotion and deployment are distinct decisions. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A project produces a tagged image during CI and then relies on a separate authorized workflow to deploy it. The guide should not silently merge those actions. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
Calling build completion ‘live release’ may prompt an operational team to skip required gates or falsely tell users that a fix is available. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Name each boundary explicitly. Preserve digest, release version and destination as identifiers, and require independent evidence that the next system accepted the intended output. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
28. Machine-readable data remains literal
Build metadata, JSON outputs, image digests, environment variable names and structured reports may be consumed by another program. Translating their keys can break automation. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
An engineering team exports a report to an audit tool, while a translation team wants a local-language explanation for human reviewers. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
If a CSV header or JSON key is treated like natural prose, automated ingestion can fail even though a person understands the translated words. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Use a separate localized commentary layer or interface labels when supported. Preserve schema, types, keys and IDs in original machine-readable outputs. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
29. Context matters for short interface labels
Terms such as build, push, save, target, cache, image and artifact overlap with everyday vocabulary. A dictionary-equivalent word can be wrong in a specific screen. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A product designer asks for one translation of ‘push’ in a developer tool’s help menu. The action may refer to pushing an image, a Git commit or a notification. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A single term applied everywhere may suggest the wrong authority or destination. Conversely, changing the translation on every screen prevents readers from learning the concept. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Create a glossary with concept, function, effect and example, not merely paired words. Check it against actual Earthly actions before approving the label. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
30. International handover and accountability
Documentation should tell readers which commands they may inspect, which have side effects, and which require credentials or approval. A translated guide is an operational tool. The distinction matters because readers must know whether they are looking at a description, an input to an executable, or a result that can be independently verified.
A new colleague joins a globally distributed release rotation. The onboarding document is the only context they have for the first unfamiliar build failure. A useful explanation names the actor and the boundary of the operation. It should distinguish the state before the command from the outcome after it, instead of replacing a complete workflow with one reassuring verb.
A translation that assumes local company habits or unexplained acronyms can mislead a competent engineer from another region. This is not merely a stylistic preference: a different token or an exaggerated claim can change what someone does next. Readers who copy instructions deserve precise syntax and a realistic account of the possible consequences.
Define roles and expected evidence, avoid country-specific idioms, and show how to escalate a failing build without sharing a token or changing a protected release configuration. For quality assurance, read the localized sentence against the original command and ask three separate questions: do the bytes still identify the same operation, would the reader expect the same side effect, and can the claimed result be checked without relying on the writer’s confidence?
A practical translation table for recurring Earthly terms
- target — a named build entry point; keep +name references unchanged.
- artifact — a file or directory output, not necessarily a publicly distributed download.
- image — a container image output; distinguish created, loaded and published.
- build context — the source files available to build steps, not the reader’s working memory.
- cache hit — reused prior result; not proof a test executed again.
- push — a remote publication action when configured, not merely a local save.
- digest — an identity fingerprint for content, distinct from a mutable human-readable tag.
- secret — a confidential value; explain its role without displaying it.
Worked walkthrough: explain a target without inventing a deployment
Suppose a repository has an Earthfile with a +unit-test target and a +package target. The unit-test target copies a small sample program into a build environment and runs a test runner. The package target depends on the tested output and saves a binary artifact. A colleague in another country must prepare a translation for onboarding. Their first job is to identify which target the command invokes, which build arguments are needed and whether a network registry is involved.
A dependable walkthrough starts with the checked-out repository, the selected Earthfile and the Earthly version. It then describes target resolution, copying source into the build environment, executing tests, producing the artifact and confirming its identity. If the artifact has not been retrieved to the host, the document says so. If the workflow has no explicit publication action, it never announces that an image is live. The explanation is useful because it marks where each kind of evidence would come from.
Now imagine the test failure says that a file cannot be found. The translator should not jump to a new command or a different cache policy. They should preserve the failing path, distinguish host and container locations, and ask whether the correct files entered the context. When the language changes, the sequence of questions remains the same. The reader gains the ability to diagnose rather than merely memorise a phrase.
Finally, the handover records the non-sensitive command line, expected target, output path, successful checks and unresolved constraints. A different colleague should be able to follow it in a safe copy of the project without needing to know the original writer’s native language. That is the practical standard of technical localization.
Hands-on review exercises for international teams
Exercise 1: Target-name trap
The prose says ‘compile’, but the invocation says +build. Translate the prose, retain +build, and explain which target the repository actually declares. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 2: Artifact-location trap
A generated binary is inside the build graph. Ask the writer what explicit action makes it available on the host before claiming that the reader can download it. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 3: Remote-push trap
A release guide contains a publishing flag. Label the remote side effect, use a non-production example and request explicit authorization for any real registry target. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 4: Cache-confidence trap
A fast CI run reuses layers. Identify which checks executed rather than treating cache reuse as fresh testing or as proof of application security. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 5: Unicode-path trap
A file with accented characters builds on one system but not another. Compare codepoints, normalization and exact path spelling before changing the Earthfile. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 6: Right-to-left trap
An Arabic explanation surrounds an ASCII target reference. Inspect the copied bytes and isolate the command in an unmodified code span. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 7: Shell-quoting trap
A Bash command is placed in a PowerShell guide. Identify the interpreter and review quotes and variables rather than translating punctuation. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 8: Secret-in-log trap
An error screenshot includes a registry token. Redact the value and keep only the failing step, status and safe context for troubleshooting. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 9: Image-tag trap
A tutorial calls a mutable tag a permanent fingerprint. Explain that the digest or verified artifact metadata provides a stronger identity statement. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Exercise 10: Release-state trap
The image builds successfully but a deployment job has not run. Replace ‘the fix is live’ with a statement limited to the verified build result. In the review discussion, ask the translator to state the original claim, the supported claim and the evidence still missing. This habit makes errors visible before a guide is distributed to teams who might act on it under pressure.
Frequently asked questions
Should I translate Earthfile instructions?
No. Treat Earthfile keywords and executable syntax as code. Translate comments and human documentation only where their role and encoding are understood. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Is earthly +build always the correct command?
No. +build is a common illustration, but actual repositories declare their own target names. Inspect the Earthfile and use the names that exist. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Does SAVE ARTIFACT upload a file?
Not by itself. It makes an artifact available through the build graph. Retrieval, host export or another delivery mechanism is a separate claim. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Does SAVE IMAGE mean the image is in a registry?
No. Saving an image and pushing it remotely are different events. Describe and verify the intended output destination. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
How should a translation describe cache hits?
As reuse of earlier build results, subject to the configured cache and inputs. Do not equate the hit with freshly executing tests. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Can I translate image tags?
No. Tags and repository references are executable identifiers. Explain their purpose in surrounding text without changing their literal spelling. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
What if the official examples use a different version?
Check installed help and the versioned documentation. State the compatibility boundary and avoid presenting an older flag as universal. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Why does command copying fail from some translated pages?
Rich typography, smart quotes, hidden direction marks or whitespace may alter shell input. Compare literal bytes in a safe example. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
How should right-to-left languages display CLI commands?
Keep command tokens isolated as left-to-right code, verify copying, and do not insert directional characters into exact identifiers. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Is a successful build enough to claim a deployment?
No. Build, image publication and runtime deployment require separate evidence and frequently different permissions. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
What does the translator need from the engineer?
The working source command, version, expected state, actual output, safety constraints and a contact for reviewing behavioural meaning. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Should every error message be translated?
Not always. Machine messages and exact diagnostics may need to remain literal, with a separate plain-language explanation for readers. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Can a public tutorial include a real secret?
No. Replace secrets with clear placeholders; if a genuine value has leaked, treat it as a security incident, not a copyediting problem. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
What is the release-ready quality test?
Have a bilingual reviewer and a technical reviewer independently verify the syntax, the implied action, the actual result and the readability of multilingual output. For a working team, document the specific command and outcome tested rather than issuing a universal promise. Readers should be able to distinguish guidance from executable data and determine what remains to verify.
Official references and further learning
- Earthly documentation: https://docs.earthly.dev/
- Earthly getting started and Earthfile targets: https://docs.earthly.dev/basics/part-1-a-simple-earthfile
- Earthly command documentation (versioned reference): https://docs.earthly.dev/earthly-0.7/docs/earthly-command
- Earthly best practices (versioned guidance): https://docs.earthly.dev/earthly-0.6/best-practices
Use the official material matching the installed Earthly release for operational syntax. This guide focuses on how to explain that syntax accurately to people in different languages, while keeping the build, publication and security boundaries visible.