How do you translate ORAS CLI commands for OCI artifacts, file push and pull, attach operations, referrer discovery and media types without changing the artifact a reader publishes? This ORAS localization guide serves technical translators, documentation teams and developers worldwide. It explains exactly which strings must stay runnable, which ideas need natural-language explanation, and how to review international tutorials for Unicode, registry permissions and operational safety.
ORAS, short for OCI Registry As Storage, lets people store and distribute content through OCI-compatible registries. It is especially useful when the payload is not a runnable container image: a document, an application configuration, a metadata file or an artifact associated with another manifest. The crucial difference is between the content being carried, the manifest that describes it and the repository reference that locates it. Accurate language keeps those layers separate.
This article follows ORAS CLI 1.3 documentation as a reference point and distinguishes stable commands from preview or experimental features. It starts with definitions and a quick safety route, then teaches artifact types, push and pull, attach and referrers, layouts, authentication, international text handling and practical quality assurance. Every example is illustrative; readers should confirm their installed command help and use only approved test registries.
ORAS command map: distinguish reads from writes
The commands below demonstrate categories rather than make a claim about a live repository. Reading help or inspecting a manifest is conceptually different from publishing a file or changing a tag. As with any CLI, inspect local help before using flags from a guide. An illustrative hostname is deliberately used so the code cannot be mistaken for a working production target.
oras version
oras --help
oras repo tags registry.example.org/team/manuals
oras manifest fetch registry.example.org/team/manuals:v1
oras pull registry.example.org/team/manuals:v1
oras push registry.example.org/team/manuals:v2 handbook.pdf:application/pdfThe final line is a remote write example. It is not a safe exercise until the registry and file have been replaced with an approved test fixture and permission has been confirmed. The others may also require credentials. A translated guide should make that distinction before showing the sample.
1. ORAS is a registry tool for artifacts beyond images
ORAS means OCI Registry As Storage. It can package and distribute files through an OCI-compatible registry, using OCI manifests, blobs and references. A reader may manage documentation bundles, configuration files or other supply-chain artifacts without creating a runnable container image. The translated guide must resist the common shortcut of calling every object ‘a Docker image’. The storage protocol is shared, but the meaning and expected consumer of the payload may be entirely different.
Ask readers whether a particular artifact is intended to execute as a container, to be read as a document, or to be attached as metadata. That answer changes the explanation even when the registry URL looks familiar.
2. Use official 1.3 documentation with version awareness
The ORAS documentation distinguishes stable operations from preview or experimental commands, and its command list changes as the project evolves. This article refers to the ORAS CLI 1.3 documentation as a checked learning reference, not a promise that every installed binary has identical flags. A translator should avoid copying old examples that use deprecated compatibility controls without checking their context. A concise version note is more useful than presenting one sample as timeless.
Read oras version and the relevant –help text before editing runnable snippets. Preserve the command’s original availability warning, especially where a guide names a preview or experimental feature.
3. A registry reference combines several identities
A reference can contain a registry host, repository path, tag or digest. Those elements answer different questions: where an artifact is stored, what namespace contains it, what human label points to it and which content identifier selects it exactly. File names within an ORAS artifact are another layer again. Translation may explain the pieces in natural language, but must not rewrite a host, repository path or digest used by a real command.
Use registry.example.org/team/manuals:v1 to identify four components. Invite a reviewer to copy the reference into a plain-text editor and check that no smart quotes, language-specific punctuation or spaces were introduced.
4. The difference between push and pull
oras push uploads local content and creates a registry artifact; oras pull retrieves content from a registry or supported OCI layout into a local destination. These are not synonyms for general file synchronization. A translated tutorial that reverses the verbs can lead readers to write to a registry when they expected to download. It should name the source and destination, identify the remote write effect and distinguish the data being transferred from the reference that addresses it.
Create an action map with arrowless labels such as ‘local file is source’ and ‘registry repository is destination’. Test whether a second reader can predict which side changes before seeing the command.
5. Local files become blobs with metadata
When files are pushed, their bytes become blobs referenced by descriptors and a manifest. The manifest is a structured inventory that lets clients find the payload. A human translation should not imply that ORAS automatically converts the content into a standardized document format. The original file may remain JSON, text, a compressed archive or another type; how an application interprets that content depends on its own conventions.
Ask the learner to distinguish a payload’s bytes, its file name, its media type and the manifest descriptor. A good answer notes that a descriptive label does not validate the file’s actual contents.
6. Artifact type tells consumers what the object represents
An artifact type is a media-type-style identifier communicating the nature of the attached or published object. Its precise meaning depends on conventions adopted by producers and consumers. Translating the phrase ‘artifact type’ is fine, but modifying a string like application/vnd.example.manual.v1 may break a filtering or compatibility rule. Avoid presenting a fictional identifier as an established public standard.
Require every artifact-type example to be labelled either a known specification value or a clearly illustrative custom type. Reviewers must not substitute a translated brand name inside the machine string.
7. File media type and artifact type are not identical
A file’s media type describes its content representation, such as text/plain or application/json. The artifact type can describe the purpose of the overall OCI artifact containing that file. Confusing these levels causes metadata that is too vague or incorrectly specific. A localized guide should demonstrate that several files may be grouped while the artifact has a separate role. The underlying strings are protocol labels, not text to translate.
Provide a package with a PDF and a JSON index. Ask which identifier describes each file’s content and which may describe the collection as a whole.
8. oras push examples must name a safe target
A push example is a write operation against a registry namespace. It may create a new reference or replace an existing tag depending on repository policy. Public documentation must not invite readers to use a shared production destination or to paste a real credential into a demo. The source files may also contain confidential information that should never become registry content.
Describe a fictional approved test registry and test files. Require the reader to state who owns the destination and whether the tag may be reused before any actual push.
9. oras pull can create local files
Pulling an artifact may write files to a local directory. A translated guide should say where the files are expected to appear, how naming collisions will be handled and when a separate clean directory is prudent. ‘Download the artifact’ is too vague if a reader does not understand which files will be produced. Some artifacts contain multiple files, and file names themselves can carry meaningful Unicode characters.
Practice in an empty temporary directory and inspect the expected output paths before using a command. Avoid promising that a specific archive or file will exist unless the fixture really contains it.
10. Attaching artifacts to a subject
The oras attach workflow associates a new artifact with another artifact designated as its subject. A software bill of materials, report or other related file may be attached in this manner. The relationship is structural, not just a sentence saying one file belongs to another. A translator must keep the subject reference, artifact-type string and payload file distinct; otherwise the example may link metadata to the wrong release.
Use a sketch with subject digest A and related artifact digest B. Ask which item existed first, which one is being published, and where the relationship is recorded.
11. Referrers show relationships, not endorsements
The discover workflow can find artifacts that refer to a subject. Discovery demonstrates a stored relationship, not automatic proof that every discovered file is accurate, authorized or safe. A localized guide must avoid claims that ‘discover’ verifies the truth of a report or signature. Readers should understand that additional tools and trust policies may be needed to evaluate the attached content.
Present a subject with a mock SBOM and a fictional note attached. Have readers describe the relationship without claiming either document has been audited.
12. The OCI referrers API and registry support
The OCI distribution ecosystem includes ways to discover artifacts referring to another manifest. Server behavior, permissions and supported features can affect results. A tutorial that works against one registry is not a guarantee of identical behavior everywhere. Translate compatibility notes carefully and avoid assigning a universal cause to an empty referrer result. It can indicate missing artifacts, authorization or implementation differences.
Design a diagnostic card recording registry version or service, subject digest, credentials, operation and observed response. Ask which evidence is needed before calling an artifact ‘absent’.
13. The subject digest must point to the intended object
A subject can be identified by a digest that represents a specific manifest. A tag may later move, but the original subject digest remains a specific identifier. Confusing a tag string with an immutable subject can lead to reports attached to an unintended release. Translators should label which reference is symbolic and which is content-addressed. This is particularly important when a bilingual instruction contains several lookalike hexadecimal strings.
Write a two-step review: resolve the intended subject, then confirm the digest in the attach example. Do not improvise a digest or shorten it in executable text.
14. Repositories and tag listings
oras repo ls and oras repo tags support exploration where the registry permits listing. Repository enumeration may be unavailable or restricted, and a tag list is narrower than a catalog of every artifact in a service. Translators should avoid turning a permissions error into a claim that a repository does not exist. They should explain that tags are names at the repository level and that listing visibility is a server-policy issue.
Ask the learner to compare a repository list, a tag list and a manifest fetch. Each answers a different question; translate the action in a way that reflects that scope.
15. oras manifest fetch reads structure
A manifest fetch gives a machine-readable description of the object, including its schema and descriptors. It is not the same operation as pulling all referenced file payloads. Translating JSON keys inside the manifest breaks the fidelity of a captured response. A reader may use the output to check media types, descriptors, sizes and relationships before deciding whether the payload is appropriate for a workflow.
Pair a manifest with a reader-friendly field glossary. The language can change; the underlying keys, digest strings and numeric values in the specimen should not.
16. oras blob fetch and file contents
Blob-level commands work with individual content objects rather than an artifact as a complete logical package. A writer should clarify whether a lesson retrieves a particular blob, a manifest or an artifact’s set of files. Confusing the levels can create unexpected local output or incomplete records. Some commands operate directly against OCI layouts as well as registries, so the destination type must be named.
Make an object map from manifest to descriptors to blob bytes. Ask a learner to point to the exact object a chosen operation is expected to retrieve.
17. oras cp is a registry copy, not translation copy
The cp command copies artifacts between references and may affect remote destination state. In ORAS 1.3 documentation, copying an image index has defined handling for its referenced manifests. Other options and recursive behavior must be checked against the installed version. Translate this operation as an artifact transfer and emphasize ownership of the destination rather than as a harmless text-copy step.
Use two fictitious registry references and ask the reviewer to label source and destination. If the destination already has the same tag, the example needs a written overwrite-policy check.
18. Recursive relationships require deliberate scope
An artifact may have attached artifacts and other relationships. A copy operation with recursive behavior can carry more data and more sensitive metadata than a reader first expects. The source article should make clear which graph is in scope. Not every target has the same permissions or registry compatibility for all linked artifacts. Translation must not collapse ‘copy the subject’ and ‘copy the subject with related artifacts’ into the same phrase.
Prepare a graph with one subject and two referrers. Ask which nodes an operation intends to preserve, then compare against command help before publishing the sample.
19. Local OCI image layouts as an alternative target
ORAS documentation includes operations involving OCI image layouts on disk. A local OCI layout is structured data with its own descriptors and blobs, not simply an unstructured folder of exported documents. A translation that calls it a ZIP archive or a running image loses important meaning. The same command family can therefore act on a registry or a local layout depending on arguments and flags.
Give the reader two destinations, one remote and one local layout. The task is to identify whether credentials, network access and write permissions differ; do not assume they are interchangeable.
20. Backup and restore may be experimental
The 1.3 command reference lists backup and restore as experimental. These operations can move artifacts into an OCI layout and back, but their behavior and stability require version-specific checking. A localization article should preserve the warning conspicuously. Calling an experimental command a guaranteed disaster-recovery mechanism would give readers dangerous confidence. Production recovery plans need independent testing and approved procedures.
Require a release reviewer to record the CLI version, registry support and demonstrated restore outcome. A theoretical command listing is not proof that the organization’s artifacts can be recovered.
21. Manifest index commands and multi-platform artifacts
An image index can refer to several manifests, including platform variants. ORAS exposes index-related commands with version-specific availability and experimental status. The translator should distinguish creating an index from adding a language option or translating a collection of filenames. Platform labels such as linux/arm64 are technical target values. They must not be adapted to a regional locale.
Draw an index with two manifests and label all three digests. Ask which object is modified by the proposed index operation and whether the example promises more stability than its documented status.
22. Annotations are metadata, not payload translation
OCI annotations can record descriptive information alongside artifact objects. Some fields may be intended for human display; others participate in conventions consumed by software. The label and value should be classified before translation. A note like ‘summary’ may safely be explained in another language, while an annotation key used for machine matching must remain exact. The translated document should not quietly mutate stored metadata.
Have a reviewer sort example annotations into prose displayed to people, standardized keys and unknown application-specific values. Technical ownership is required for unknown entries.
23. JSON, YAML and media-type strings need byte accuracy
Machine-readable keys, MIME-like media types, JSON syntax, YAML indentation and Unicode escaping can affect consumers. Translating a code block as ordinary text may introduce curly quotes, full-width colons, wrong indentation or re-encoded line endings. Human-facing descriptions should be localized beside the data, not inside parser-controlled structures. This is especially relevant when a guide includes a small JSON payload used in push or attach examples.
Copy the sample into a syntax-aware parser and compare it with the original. A grammatical translation passes only if the sample still parses and conveys the intended exact values.
24. Archives and compressed payloads
An ORAS artifact may carry an archive, but ORAS itself does not guarantee that every payload is a ZIP or tar file. Describing all ORAS content as an archive confuses transport packaging with the representation of the user file. A localization guide should explain what kind of file is in its chosen fixture and whether a separate program is needed to open it. File extensions alone are not reliable proof of content.
Show three payload names and declared media types. Ask which files can be read directly and which need another tool, without pretending to infer security or validity from the filename.
25. Authentication and permission boundaries
Pull and push permissions may differ, and artifact discovery can require authorized reads. ORAS supports registry authentication commands and related configuration, but documentation should avoid showing live access tokens or password strings. An instructional screenshot can accidentally reveal repository names and private account identifiers even when the obvious credential is hidden. Translators also need to distinguish authentication failure from authorization denial.
Review sample output for secret values, server paths and user names before publication. Use fictitious credentials, follow the organization’s approved secret channel and state when a step writes remote content.
26. Plain HTTP and insecure transport flags
Some ORAS examples reference flags for intentionally insecure or plain-HTTP registries, commonly in local demonstrations. A global public article must not present these as general recommendations for production. Translating the warning is as important as translating the command. Readers should understand the difference between local development conveniences and real network trust. A command can be syntactically correct while unsuitable for sensitive data.
Label every insecure example as lab-only and require secure transport in production guidance. Before translating a security-related flag, check its exact semantics in the installed version.
27. Unicode in artifact filenames
A local payload may have a filename containing accents, CJK characters or combining marks. The filename may be embedded in artifact metadata, copied to another file system or shown in a terminal. Normalization differences and reserved characters can create unexpected behavior. Translators should not silently rename an actual file inside a runnable example. They may translate a fictional filename only when every reference to it changes consistently and the sample remains tested.
Create a temporary file with a non-ASCII name in an approved fixture. Follow its exact representation through push metadata, pull output and the article’s copied code block.
28. Right-to-left layouts around OCI references
Registry references combine slashes, colons, digits and digests, all usually intended to remain left-to-right. Arabic and Hebrew paragraphs can reorder those visually. A translated publication should isolate code, label the reference’s role and avoid inline strings that wrap unpredictably. The user must be able to copy the exact stored bytes even if the display order is challenging.
Inspect mobile RTL rendering and compare copied text with the original. Do not accept a screenshot that looks plausible as proof of byte fidelity.
29. Windows PowerShell versus POSIX shells
Quoting and line continuation differ between shells. An ORAS command copied from a Unix-style tutorial may not run unchanged in PowerShell, and vice versa. A world-facing article should clearly label the shell used by an example instead of calling one syntax universal. Translators should not replace hyphens or quotes as typographic decoration, and should avoid inventing new shell behavior in another language.
Test each multi-line command in the named environment or simplify it to a shell-neutral single line. A syntax check cannot be replaced by a grammar review.
30. Errors deserve evidence-based explanations
A 401, 403, 404, rate-limit response or timeout may come from different stages of registry access. An empty discovery result may be a real absence or a visibility limitation. Translation must keep diagnostic uncertainty intact instead of making an ambiguous English statement certain in another language. Write what the reader can observe, what information to collect and which safe next check follows.
Build a troubleshooting tree based on reference, credentials, command, status code and registry capabilities. Avoid suggesting repeated writes until the previous outcome is understood.
31. Security claims must not be inferred from attached files
An SBOM is a record of software components, not proof that the software is safe. A signature artifact may be discoverable without its trust being verified. A provenance statement may describe a process without independently proving every claim. ORAS is primarily an artifact transportation and storage interface. Translators should not upgrade ‘attached’ into ‘verified’, ‘compliant’ or ‘approved’ unless a separate validation actually occurred.
Give readers three sentences with the verbs attached, inspected and verified. Ask which evidence supports each. The tool’s ability to transfer bytes does not certify the claims inside them.
32. Large payloads and operational limits
Artifact sizes, quotas, network behavior and server limits may influence push, pull and copy results. A translated example should not promise that every registry accepts every payload size. If a transfer stalls, the remedy may involve storage limits or network policy rather than language or command syntax. Reader guidance should distinguish configuration assumptions from guarantees provided by the CLI.
Capture the expected object size, destination quota and error context in a test record. Don’t encourage unbounded retries or editing a file merely to silence an error.
33. Source files, repository policies and compliance
A reader may have rights to download a file without rights to redistribute it to another registry. The transport mechanics do not resolve licensing, privacy or export-control requirements. This is particularly important for world-facing tutorials that readers may follow across jurisdictions. Translation should state the operational distinction without pretending to give universal legal advice. Always use authorized fictional or openly licensed fixtures for teaching.
Add a preflight question: who owns the payload and who approves its destination? The exercise should be reversible, authorized and free of customer data.
34. Human-friendly summaries and structured output
Tool output may appear as a short terminal summary or as machine-readable JSON. A translator can explain the summary’s meaning, but a captured sample should match what the tool actually emits. Invented output can cause readers to search for a nonexistent field. Names that look natural-language-like may actually be flags, keys or exact error fragments. Preserve the underlying interface when building glossaries.
For each screenshot, record the source version and operation. If a message is paraphrased for clarity, label it as explanation rather than as verbatim terminal output.
35. Documenting the acceptance evidence
A localization reviewer needs more than a word-count report. For ORAS, a useful evidence packet includes the version, payload fixture, registry target, expected manifest role, a list of protected literals and visual checks for non-Latin and RTL text. Write operations need destination approval. Reviewers should be able to reproduce safe read steps, compare expected descriptors and flag any claim that goes beyond demonstrated output.
Ask a second person to follow the first safe exercise without background knowledge. If they cannot distinguish the payload from its reference or the subject from its attachment, revise before publishing.
36. Use cases that truly belong to ORAS
A translation tutorial should answer why an organization chooses ORAS: distributing non-container files with OCI tooling, attaching related artifacts to release subjects, sharing content-addressed payloads or preserving a structured local layout. It should not turn into a generic tutorial about how Docker runs containers, how to build applications or how to verify every signature scheme. Clear scope lets readers find the next relevant guide rather than compete with adjacent documentation.
Finish with a choice exercise: which task needs ORAS transport, which needs an image builder, which needs signature trust verification and which needs runtime operations? Distinct answers support distinct learning routes.
Worked cases, questions and further reading
Quick answer: what can be translated?
Localize the human purpose of the command, learning headings, workflow descriptions, warnings, troubleshooting questions and explanations of data fields. Preserve executable CLI names and flags, hostnames, repository paths, digests, JSON keys, media-type strings and file references that must match a real file. If a file name is part of a tutorial fixture, treat it as an exact identifier until the whole example is rebuilt and tested. Never replace a runnable OCI reference with a natural-language translation.
Suggested safe exercise before a registry write
Begin with oras version and oras –help. Then use an authorized, already existing test artifact to inspect its manifest or list tags where permitted. Record the expected reference and the actual result. Avoid a real push or attach until you have permission to modify the destination. This sequence teaches readers how to identify the object first, inspect what is present and only then make a considered change. It is safer than beginning with a copy-pasted write command.
Case study: one PDF and one JSON metadata file
Imagine a training team wants to publish a handbook PDF with a machine-readable contents index. The PDF has its own media type, the index may be application/json, and the artifact collection has a purpose represented by an artifact-type identifier. A vague instruction saying ‘push the document image’ hides those distinctions. A correct translation explains the files, the artifact reference and which consumers interpret the attached metadata. The reviewer checks the fixture’s actual file names and exact types before approving the tutorial.
Case study: a release SBOM linked to the wrong subject
A team has two releases with similar tags and attaches an SBOM to the earlier one. The problem is not necessarily that the SBOM text was translated poorly; it is that the subject reference identified the wrong manifest. The corrected guide asks the reader to resolve the intended release digest before the attach operation and to inspect the discovered relationship afterwards. The guide should not claim that ORAS validates the accuracy of the SBOM, because transport and verification are different tasks.
Case study: a registry cannot discover a referrer
A reference that worked in a local test does not reveal the expected attachment in another environment. The editor should not immediately say the artifact is lost. Different registry capabilities, permissions, subject choices or failed writes could explain the observation. Document the exact subject digest, server, credential context and response first. Only then choose the next safe diagnostic. An internationalized error guide should preserve uncertainty while still helping a reader make progress.
Case study: an accidental production write
A sample uses a destination that looks like a real organization repository. A reader copies it without noticing that the command is a push, not a pull. The improved publication replaces the destination with an explicit fictional address, labels the operation as a remote write and asks the user to substitute an approved test namespace. The improvement is not cosmetic. It changes a risky ambiguous instruction into a bounded exercise with a verifiable expected result.
Case study: Arabic prose and a copied JSON example
A page places Arabic instructional text around a JSON code block containing a digest, media type and repository path. The display looks correct but a text processor has converted quotes and line endings. The fix is to protect the code as a literal block, retain the parser keys and test the copied bytes. Reviewers examine the explanation separately from the raw sample. Successful localization means both a human and a parser receive the intended meaning.
FAQ: must every ORAS artifact be a container image?
No. ORAS is designed to handle arbitrary OCI artifacts, including non-runnable files. The registry model overlaps with container images, but consumers may use the payload for documentation, configuration or metadata rather than runtime execution.
FAQ: does discover verify a signature?
No. Discovery finds related artifacts. Verification requires interpreting the content and applying the appropriate trust model with tools intended for that purpose.
FAQ: can I translate application/json into my local language?
Explain what it means in prose, but preserve the media-type identifier in machine-readable metadata and command examples.
FAQ: why did pull create more files than expected?
The artifact can contain multiple payloads or related behavior depending on the command and options. Inspect its manifest and the exact version-specific command before assuming the output is corrupt.
FAQ: is an empty tag list proof of an empty registry?
Not necessarily. Repository scope, permissions and registry listing behavior affect what a client can see. Record the evidence before asserting a cause.
FAQ: are preview and experimental ORAS commands safe for production?
They should not be presented as stable guarantees. Verify the exact release documentation and test the organization’s recovery and compatibility needs independently.
Final publication checklist
An excellent ORAS tutorial states the task, correctly identifies the object and its reference, names which side changes, protects machine literals, shows the expected evidence and keeps security limitations visible. It can be read without insider knowledge and checked without exposing credentials. Before publishing, test a supported read operation, verify all copyable code, inspect mobile and right-to-left rendering, then confirm that every remote write example has an explicit permission boundary.
Official references for readers
Use the ORAS project CLI 1.3 command reference at https://oras.land/docs/category/oras-commands/ and the ORAS pull documentation at https://oras.land/docs/commands/oras_pull/ . The OCI specifications are at https://github.com/opencontainers . Treat these as living documentation. Confirm the binary installed in the reader’s environment, especially for preview or experimental operations. The article focuses on translating these workflows, not replacing upstream product documentation.