Azure CLI Cosmos DB localization means translating documentation for the `az cosmosdb` command family while keeping commands, account identifiers, API families and machine output semantically intact. If you need to translate Azure Cosmos DB CLI help, account and database administration, NoSQL containers or JMESPath `–query` expressions, the essential skill is to tell readable language apart from executable syntax.
This practical guide is written for international developers, translators, technical writers, teachers and cloud support teams. You will learn to recognize subscription scope, resource groups, Cosmos DB accounts, NoSQL databases and containers, safe read-only operations, structured responses, Unicode output and publication review. Illustrative identifiers are fictional. The examples are designed to explain operations, not authorize changes to a real organization’s cloud resources.
Before copying a command, identify who is signed in, which Azure subscription is active, which resource group contains the Cosmos DB account and which database API the instructions describe. A fluent translation that silently changes one of those contexts is wrong even when every sentence sounds natural. Good technical writing lets readers predict the target and effect of each operation before they execute it.
A localized command-line guide must preserve four different kinds of information at once: the reader’s intended action, the exact machine syntax, the resource or data structure it acts upon and the evidence that the result matches the explanation. A working translation is one that keeps these four aligned. A glossary alone cannot protect this contract, because even one altered flag or quoted JSON key can change a result.
At a glance: safe localization rules
- Preserve command tokens, resource scopes, JSON keys, JMESPath and numeric units.
- Translate conceptual explanations, warnings, learning questions and user-facing labels.
- Use an approved identity, a documented shell and fictional examples.
- Distinguish read-only inspection from changes to cost, configuration or availability.
- Verify content with both language and cloud-operations reviewers.
A guided path from the resource map to usable documentation
1. Understand the subscription before opening the service
An Azure subscription governs a set of Azure resources and is associated with billing, permissions and organizational controls. It is not the same thing as a Cosmos DB account. In a translated tutorial, a sentence such as ‘select the subscription’ must not become ‘select the database’ simply because both involve selecting something. The reader needs to know which boundary controls the following request.
Give learners a fictional subscription named `training-sub`. Ask them why the next account lookup should happen inside that context rather than any subscription they happen to see. If the answer mentions authorization and resource scope rather than screen language, the translation has taught the important distinction.
2. Draw resource groups as containers of Azure resources
A resource group manages Azure resources together. It should not be confused with an Azure Cosmos DB container, which is a different kind of application data resource. This distinction is especially important in languages that use one ordinary word for ‘group’, ‘collection’ and ‘container’. Technical clarity may require two or three different terms where everyday speech would use only one.
Draw `rg-reading-lab` holding the Cosmos DB account `cosmos-training`. Place database `learning` and container `chapters` below the account. Ask a beginner which value follows `–resource-group`. The answer must be the resource group name, not the database or the application’s item collection.
3. Treat the Cosmos DB account name as a literal identifier
The `–account-name` flag identifies the Cosmos DB account resource. The account name may resemble a noun that translators would normally translate, but a real CLI resolves its literal characters. Substituting a local-language synonym could refer to no account at all, or an unintended resource in a different environment. Preserve identifiers in code and clearly distinguish them from explanatory labels.
For a public example use a transparently invented value such as `cosmos-training`. Explain in nearby prose that readers must verify the authorized account name before substitution. The fictional example should remain consistent across headings, commands, screenshots and expected results.
4. Recognize the API for NoSQL command family
Azure Cosmos DB supports several API families. The Azure CLI group `az cosmosdb sql database` is associated with Cosmos DB for NoSQL administration. The token `sql` is part of the command namespace and must remain unchanged, even though the reader should not mistake this for a generic relational database CLI. A translation should clarify the product distinction without modifying parser tokens.
If a source page concerns a MongoDB API account, do not copy NoSQL-specific commands into it and hope that natural-language adjustments will make them work. Ask the technical owner which API is in use and check current help for that branch before producing executable examples.
5. Preserve command names while translating the purpose
Words such as `az`, `cosmosdb`, `sql`, `database`, `container`, `list`, `show`, `create`, `update` and `delete` can be executable subcommands. Their spelling matters to the parser. Readers should nevertheless receive a natural, idiomatic explanation of what each command is for. The easiest editorial convention is to place literal tokens in code styling and ordinary instructions in paragraphs.
Compare ‘List the NoSQL databases in this account’ with `az cosmosdb sql database list` as an illustration of separate layers. The first sentence is translated; the second stays literal. Verify the actual required flags against `–help` rather than assuming a shortened sample is executable.
6. Learn the difference between list and show
`list` usually requests a collection of resources in a scope; `show` describes one identified resource. This difference is not cosmetic. A list response may contain an array of names and metadata objects, whereas a show response targets one resource. Translators should not describe either as an export of all customer records stored in the database.
Teach with a fictional account containing `learning` and `archive-lab`. Ask what question each operation answers. A correct response says list discovers available database resources, while show inspects the configuration or metadata for the named database. This prevents a common false claim in tutorials.
7. Separate metadata inspection from item retrieval
Administrative listing and describing commands return resource information. They do not automatically read or back up the application documents inside every NoSQL container. A translation that claims ‘all records are exported’ merely because resource names appeared is seriously misleading. Data access involves separate APIs, queries, permissions and sometimes different costs or privacy rules.
Provide a made-up response listing two databases, then ask which actual application items could be recovered from it. The answer is none: knowing resource names is not equivalent to having exported stored documents. Keep that distinction in headings and conclusions.
8. Treat containers as configured data resources
An Azure Cosmos DB for NoSQL container holds items and has partitioning and throughput characteristics. Translating it as an ordinary folder may hide operational behavior that matters to developers. A reader should understand that a container is a defined resource, not just a decorative grouping in the Azure portal.
Use the imaginary hierarchy account `cosmos-training`, database `learning`, container `chapters`. Explain why `chapters` is a resource identifier in a command but ‘the chapters container’ is descriptive prose that can be translated. Compare this with a generic folder metaphor and identify what the metaphor fails to express.
9. The partition key is part of the application contract
A partition-key path such as `/studentId` refers to a specific property path in application data. It is not a translatable label. If a multilingual application changes its visible label from Student ID to another language, that does not by itself mean its underlying JSON property or partition-key configuration should change. Making that change would be a schema and deployment decision.
Give two columns: user interface text and stored key. Let learners translate the interface text while leaving `/studentId` intact. Ask an engineer to verify that the example reflects the actual partition design. Do not claim that changing a path is a harmless localization improvement.
10. Distinguish throughput from a count of requests
Azure Cosmos DB request units measure computational work. RU/s therefore describes request-unit throughput rather than a guaranteed number of API calls each second. Translators should preserve values, units, limit types and whether throughput is attached to a database or a container. Confusing these dimensions affects capacity discussions and costs.
A source example mentioning 400 RU/s must not become 400 users or 400 requests per second in translation. Explain why two operations may consume different request units. Review numbers and units separately from wording, much as a science editor checks measurements.
11. Account modes change which instructions apply
Serverless and provisioned-throughput account modes have different billing and operational models. A localized document should never reduce that distinction to an inaccurate free-versus-paid label. An example that adjusts provisioned capacity may not apply to the account mode in the reader’s environment. The right response is to explain the prerequisite, not to guess another command.
Give students two fictional account descriptions and ask them to identify which configuration questions must be resolved before following a throughput tutorial. The learning goal is to read constraints, not to deploy anything.
12. Autoscale has explicit boundaries
An autoscale throughput setting is not a promise of unlimited traffic or automatically reduced bills. Configuration includes specific capacity concepts and can have workload and financial implications. Technical translation should preserve maximum values, mode and units without replacing them with marketing language.
Ask learners to compare ‘automatically scales without limit’ with ‘uses the configured autoscale maximum’. The first overstates what a setting means; the second preserves a necessary constraint. For current supported options, point to the official reference and the actual account mode.
13. Do not confuse region with translation locale
An Azure deployment region determines where infrastructure runs or replicates. A translation locale determines what language a person reads. These are independent decisions. A writer cannot substitute a region closer to the target audience merely because it looks culturally appropriate. Such a change could affect data residency, latency and availability.
Imagine translating a guide into Korean while retaining a fictional resource already deployed elsewhere. Explain that the translated language does not move that resource. Make the environment’s selected region visible as a technical fact, not an editorial preference.
14. Protect readers from mutating commands
Commands that create, update, delete or alter failover state can change resource configuration, cost, availability or retention. That is fundamentally different from inspecting metadata. A translated beginner guide should place read-only orientation first and describe mutating operations as separate, permissioned procedures.
Give learners a set of command verbs and ask them to classify each as inspection or mutation. Require them to explain the possible consequence rather than judging from how friendly the verb sounds. In public examples, do not include irreversible operations as casual cleanup steps.
15. Authentication never implies unlimited permission
`az login` and related approved authentication flows establish identity context; they do not guarantee that every Cosmos DB administrative operation is authorized. Organization policies, roles and network controls can still limit access. A translation that says ‘sign in to unlock all databases’ is both unsafe and inaccurate.
Explain least-privilege access and the need for approved training accounts. When using screenshots, remove tenant details, keys and real user information. Avoid instructing learners to switch to an administrator identity just to suppress an error.
16. Use current help and the documented shell
CLI syntax changes with versions and extensions. Command-line quoting also differs among Bash, PowerShell and Windows shells. A translated code sample should identify the intended shell and preserve quote characters, line continuation and literal flags. A typographical smart quote may be fine in prose but break a command.
Ask a reviewer to copy a rendered example into a plain-text buffer and compare each character to the validated source. Record the CLI version and relevant documentation reference. Avoid claiming that an untested sample was executed successfully.
17. Know where JSON ends and translation begins
Azure CLI frequently returns JSON. Its keys, nesting, brackets and string escaping are structured data, not ordinary sentences. Translating a property named `name` inside a real sample could break later filtering. It is better to preserve keys and explain their meanings in a separate paragraph or table.
Provide a clearly fictional JSON object and let a student identify the exact fields used by the example. Then invite them to write natural-language descriptions for those fields. Parsing the sample verifies syntax; bilingual review verifies explanation.
18. JMESPath output queries are code
The global Azure CLI `–query` flag uses JMESPath to reshape or select fields from a response. Expressions such as `[].name` contain exact property names and operators. They are not sentence fragments that should be translated. Also, selecting output locally does not mean the database server performed a cheaper operation.
Take a synthetic array with two `name` fields and ask what `[].name` would return. Explain that the answer depends on the input JSON shape. The expression is a useful illustration of client-side projection, not a database query language lesson.
19. Presentation formats cannot secure data
Azure CLI output formats include machine-readable JSON and more concise human displays such as tables. A table can omit fields; that does not make the underlying operation safe or remove permissions needed to obtain the original response. Translate the reason for a display choice without claiming it is a security barrier.
Compare two representations of one imaginary response. Ask which fields a person no longer sees and whether the service operation changed. This teaches why redaction, authorization and output formatting must be evaluated separately.
20. Troubleshoot the stage that failed
A missing resource, insufficient authorization, wrong subscription, malformed CLI flag and shell quoting issue call for different corrections. A single translated message such as ‘the database is broken’ does not diagnose any of them. Accurate technical help should identify evidence, preserve uncertainty and avoid overpromising a fix.
Teach a diagnostic ladder: verify identity and subscription, compare group and account names, inspect current CLI help, check role permissions, then examine the specific error class. Never recommend broad privilege escalation as the universal solution.
21. Make output projections visible in explanations
A translated guide should explicitly distinguish all fields returned by an Azure request from the subset printed by a `–query` expression. This becomes crucial when a later troubleshooting step requires fields hidden by the friendly view. A screen that shows only names may be adequate for orientation but insufficient for checking identity, provisioning state or other resource attributes.
Give learners both a full fictional object and a projected list of names. Ask what information has disappeared and what information was never requested. Let them explain why the projection is a display decision rather than a promise about the backend operation.
22. Write error messages that preserve uncertainty
An error response may suggest a resource was not found, but it may also reflect unavailable access, a mistaken subscription or a malformed request. Do not translate a diagnostic into a categorical accusation that a database has been deleted. Preserve the exact error token where it is useful, then explain the likely diagnostic stage in ordinary language.
A worked exercise asks students to choose one verification question for each possible cause. The goal is not to invent a fix, but to narrow the failure without deleting resources, changing access policies or sharing secrets with an untrusted person.
23. Choose stable placeholder conventions
A public tutorial needs sample names, but placeholders can accidentally be mistaken for literal production values. Pick obviously fictitious resource names and explain how they map to the authorized environment. Use clear formatting for placeholders that cannot be executed unchanged, while preserving command syntax around them.
Review whether every example refers to the same imaginary subscription, resource group and account. A patchwork of unrelated samples can make a careful reader think multiple resources are involved when the lesson is about only one.
24. Do not localize account keys or credentials
Connection strings, authentication tokens and account keys are sensitive. They are not examples of text that should be reworded for readability. Public documentation should avoid live credentials entirely, using redacted screenshots and nonfunctional placeholders. A localization system that copies private strings into translation memory can create a second exposure.
Build a small checklist that covers source files, screenshots, alt text, copyable blocks and the draft’s revision history. Ask the security reviewer to confirm there is no sensitive material before the post becomes publicly indexed.
25. Handle case and punctuation as data
Capital letters, hyphens, underscores, slashes, colons and curly brackets have different significance depending on whether they appear inside a natural sentence, an identifier, a shell command or JSON. A typography pass must not treat every occurrence of punctuation as editable prose. Normalizing a resource identifier can make it invalid.
Present a few deliberate contrast pairs: a translated heading with proper typographic quotation marks, an ASCII shell string and a JSON property. Invite the learner to explain where editorial freedom ends and literal fidelity begins.
26. Teach the difference between an account and an item
The word ‘account’ might mean an Azure identity, a billing subscription or the Cosmos DB service account. An ‘item’ is an application document inside a NoSQL container. This semantic range makes careless translation unusually risky. Use the precise product noun on first mention, then shorten only after its referent is clear.
Ask learners to annotate a paragraph containing all these concepts. Each should be able to point to a different node in the resource map or identity flow. Ambiguity is a reason to revise, not an expected feature of a technical translation.
27. Introduce role-based access without overclaiming
Azure permissions can depend on identity, assigned roles, scopes and service-specific access mechanisms. A command may fail although the user is correctly signed in. A translated help article must distinguish authentication from authorization and avoid presenting an administrator login as the default troubleshooting measure.
Write a plain-language warning that readers should seek the minimum approved rights for their exercise. Encourage review of the denied operation and resource scope before requesting an access change. That is safer than instructing people to ignore the error.
28. Keep pricing and capacity claims conditional
Cost statements become stale when cloud pricing or deployment options change. Translators should preserve the source’s exact billing assumptions and not convert a capacity setting into a fixed price estimate. Real charges can depend on region, mode, throughput, storage and other characteristics.
An effective example compares two texts: ‘the command configures a throughput setting’ and ‘this always costs five dollars’. The first can be verified from syntax; the second needs current pricing and account-specific assumptions. Teach readers to look for those qualifiers.
29. Distinguish database-level and container-level settings
A throughput setting or other configuration may apply at different resource levels. The distinction matters because database-level and container-level decisions can have different performance and cost implications. A translated sentence must identify which object carries the setting rather than using a generic phrase like ‘the server speed’.
Use the hierarchy drawing again, placing one setting beside the database and another beside a specific container. Ask learners which one an example command targets. This bridges vocabulary with operational reasoning.
30. Describe region replication carefully
Replication, account regions and availability terms should not be flattened into a guarantee that all data is instantly present everywhere. A cloud deployment has specific configuration and consistency behavior. Translating the source faithfully means retaining its caveats and avoiding extra assurances added for a friendly tone.
Offer an exercise in which learners underline every absolute claim—always, never, immediate, guaranteed—and decide what evidence would be needed. Remove unsupported promises rather than replacing them with another exaggerated phrase.
31. Keep a clean boundary around deletion and recovery
Deleting a resource is not the same as hiding it from a list, removing a temporary screenshot or clearing a local terminal. Recovery possibilities vary by resource and configuration. A translated cleanup section should describe authorization, possible consequences and the need to consult current product procedures.
Beginner examples should use conceptual descriptions rather than executable destructive commands. A reader can learn to recognize a delete verb without being invited to use it in an unknown environment.
32. Design a read-only classroom activity
Start with an inventory showing one fictional subscription, two resource groups and an account with two NoSQL databases. Ask learners to select a suitable inspection command family and explain the expected result type. Because no resource is real, the exercise tests understanding before connecting to cloud services.
Pair students so that one acts as an operator and the other as a translator. The operator describes the scope; the translator explains it in a second language. They exchange roles and identify any changed meaning.
33. Build a translation-repair challenge
Provide this intentionally incorrect instruction: ‘Translate the Cosmos DB account name into your language, select the nearest Azure region and delete the database to inspect it.’ It demonstrates three separate failures—identifier change, environment substitution and a destructive verb disguised as inspection. A good student must find all three.
The repair should require an authorized existing account, retain exact resource names, use a verified read-only command and explain the scope. Do not grade the task on stylistic smoothness alone; grade operational equivalence.
34. Create a synthetic output exercise
Provide two JSON objects with `name`, `id` and an invented `type`. Ask learners to explain how the `–query` projection `[].name` affects what a viewer sees. They should recognize that the expression is a client-side extraction of fields and that field spelling is literal.
Next ask them to translate the explanatory sentence into their target language without editing the JSON keys or expression. This simple exercise makes a hidden failure mode observable before production documentation is touched.
35. Explain why polished prose can still be wrong
Technical translation can fail through beautiful but false simplification. Saying ‘all data is backed up’ when a command only lists metadata is one example. Saying a region flag chooses display language is another. These errors often survive ordinary proofreading because every sentence is grammatically flawless.
Teach reviewers to compare claim and action, not just paragraph and paragraph. For each imperative, write down the exact command effect, expected object and missing prerequisites. A contradiction should block release.
36. Test the rendered page, not only the draft
Publishing systems can introduce smart punctuation, altered line breaks, auto-linked URLs, transformed HTML or narrow-screen clipping. A command pasted from a web page can differ from what the editor originally typed. Localized pages may also create overflow because sentences and labels are longer.
Copy sample commands from the public rendering into a plain-text editor and compare them to vetted originals without executing unsafe actions. Review mobile width, code blocks and the placement of warnings next to instructions.
37. Keep the glossary at the right level
A useful glossary defines resource group, subscription, service account, NoSQL database, container, item, request unit, partition key, response projection and CLI option. Some terms refer to infrastructure objects, some to application data, others to tools. Definitions must preserve those categories.
For each term, show one natural-language definition and one example of a token that should not be translated. This gives bilingual reviewers a standard against which to judge headlines, captions and troubleshooting notes.
38. Ask for evidence rather than confidence
The strongest review record distinguishes a syntax comparison against official documentation from a command actually run in a disposable environment. An illustrative screenshot is not proof that a workflow was tested. Source links, test versions and assumptions make a long guide trustworthy.
Have reviewers label each example as ‘syntax reviewed’, ‘tested read-only in sandbox’ or ‘conceptual illustration’. Public prose should never imply a successful test that has not occurred.
39. Make an editorial release matrix
Record the section, resource scope, original code, localized explanation, intended effect, security classification, expected output and reviewer. A release matrix prevents a change in one paragraph from silently contradicting a screenshot elsewhere. It also enables quick rechecking when CLI documentation changes.
Include a column for whether the example operates on live resources, and keep every beginner exercise fictional. A matrix is not busywork: it is a compact map of how the article can be verified.
40. Keep neighboring subjects separate
This guide owns Azure CLI Cosmos DB administrative localization. It does not replace a tutorial on writing application queries, designing distributed partition keys, data migration, failover engineering or general language translation. Those tasks have different readers and require deeper subject-specific evidence.
At the end, suggest that readers consult the official CLI reference for exact syntax and another specialized guide for the task they actually need next. A precise scope helps both readers and search engines.
41. Run a final learner comprehension test
Ask a new reader to explain which subscription is active, what resource group contains the account, which command lists databases, what a container holds, why `–query` is not a database query and which examples could change state. These questions reveal whether the localization communicates causal structure.
A reader who can answer them in the target language has learned the topic; a reader who merely recognizes translated nouns has not. Revise any point where the explanation fails to predict behavior.
42. Publish with explicit limitations
The final draft should state when flags were checked, which shell its examples use, whether any commands were run and which operations are only illustrative. It should preserve any unsupported or unverified behavior as a limitation rather than turning uncertainty into a confident promise.
Professional localization is an exercise in safe equivalence. Readers in different languages should make the same decisions, target the same kind of resource and recognize the same consequences, without seeing any sensitive environment details.
Worked case: five languages, one verified resource map
Imagine a company translating an internal beginner handout into Arabic, German, Spanish, Japanese and English. Its aim is to inspect the databases inside a single disposable training account. The first draft includes a real subscription ID in a screenshot, a half-finished `az` command, and a paragraph that calls a Cosmos DB container a storage bucket. The translation manager first separates human language from identifiers, then replaces the sensitive screenshot with a fictional diagram. A product engineer checks the exact command group and confirms the permissions needed for read-only access.
During review, a German draft changes an account name into a German word. The editor restores the literal resource name. A Spanish draft says the `–query` projection limits server work; the engineer corrects this to client-side display selection. The Japanese draft calls ‘delete’ a reset function; the team removes that misleading term. None of these corrections makes the article less approachable. They make its friendliness compatible with reality.
Finally, the team tests comprehension. A reader sees the imaginary account `cosmos-training`, database `learning` and container `chapters` and must answer which named resource each command could inspect. The reader also explains why selecting a different subscription would alter the target, and why a JSON property must remain unchanged even when its explanation is translated. The exercise demonstrates that understanding is transferable across languages when the underlying operational contract remains fixed.
FAQ: common questions about translating Cosmos DB CLI guides
Can I translate `sql` inside an Azure command?
No. In the command group it is parser syntax; explain its meaning but keep the characters unchanged.
Does `–output table` make an operation read-only?
No. Presentation does not change the effect of `create`, `update` or `delete`. Always classify the operation itself.
Does the Azure CLI `–query` flag query application documents?
It is a global JMESPath response-projection option. Do not confuse it with queries against Cosmos DB application data.
Should a translated sample use a real subscription?
No public guide requires that. Use plainly fictional identifiers and tell readers to verify their own authorized context.
Do list commands export database items?
Administrative resource listing is not an item-level export. Explain exactly what type of metadata is returned.
What should happen when the documentation has changed?
Recheck installed help and current Microsoft Learn references. State version boundaries instead of inventing a replacement flag.
How can a non-engineer review safely?
Compare protected code tokens byte for byte, check source links and units, and ask a technical reviewer to confirm operational consequences.
Sources and next reading
The practical standard is straightforward: keep language natural, command syntax literal, resource scope explicit and every safety claim testable. When those conditions hold, translation does not merely make Azure CLI documentation readable in more languages; it helps more readers use it with the same understanding of the system.