How do you use the Phrase Strings CLI to synchronize translations without overwriting reviewed content or losing localization keys? The phrase command works with a .phrase.yml configuration that defines source files for push and target paths for pull. This practical guide explains project setup, API regions, authentication, locale placeholders, translation-key prefixes, upload waiting, cleanup safeguards and multilingual quality assurance.
Phrase push and pull are not harmless opposites. Push can update remote strings depending on configuration, while pull can overwrite local translation files. A project can report successful transfer even when the wrong locale, file path or source revision was chosen. Reliable localization means mapping the data carefully and testing what customers will actually read.
This world-facing educational tutorial is for application developers, localization coordinators, release engineers and translators maintaining multilingual products. It focuses on the Phrase Strings CLI rather than the wider Phrase localization platform, with actionable steps for .phrase.yml, controlled file exchange, tags, formats, glossary review, Unicode and production release checks.
- Identify the Phrase Strings project, API host and trusted configuration.
- Review push and pull behavior before allowing overwrites.
- Protect tokens, source keys and complete-project cleanup boundaries.
- Test locale placeholders, prefixes, tags, format options and asynchronous upload completion.
- Validate the runtime interface, placeholders, Unicode and high-risk wording.
1. Distinguish the Strings CLI from a general translation service
The Phrase Strings CLI is a command-line interface for managing projects and locale files through Phrase Strings APIs. It is especially useful when source and translated resources belong in a software repository. It does not replace the work of translators, reviewers or engineers who own source behavior.
Before running commands, identify the target Phrase Strings project, the authoritative source-language resources and the application version being prepared. A correct authentication token can still be used on the wrong project if identifiers are copied carelessly. Establish which system owns keys, which owns word choices and which build consumes the output.
Begin with read-only project inspection and the installed executable’s help. Decide which operations are merely exploratory and which can change remote or local data. Make that distinction visible in scripts and code review so a diagnostic task does not accidentally become a bulk import.
2. Initialize from the right repository root
The official workflow uses phrase init to prepare a .phrase.yml configuration. Initialization should be performed in the repository directory that contains the language resources or in a deliberately chosen configuration scope. Running a command from a different working directory can change which files are found and where outputs are written.
Imagine a monorepo with web, mobile and documentation packages. A configuration generated under web may be appropriate for its dictionaries but not for mobile resources. Applying it from a root script without reviewing paths can lead to missing or misplaced files.
Commit a reviewed mapping configuration when it describes shared build behavior, but remove authentication secrets first. Confirm that source paths resolve correctly on Linux CI as well as on developer machines. Treat the configuration as code: changes deserve tests, a named owner and a clear rollback.
3. Read the .phrase.yml structure as a contract
The configuration identifies project and format settings, push sources and pull targets. These sections describe the relationship between remote translation content and repository files. A push source might match a set of YAML files; a pull target might use a locale placeholder to create the exact file the application loads.
A team could maintain Rails YAML files, Android XML resources and iOS strings files. Their directory conventions differ. One broad pattern should not flatten all three into a folder merely because their content can be translated in the same service.
List every input and expected output path in a small test. Review glob matching, format selection, permissions and locale names. A configuration is correct only when a clean checkout can generate files that the actual application uses without manual renaming.
4. Configure the correct regional API host
Phrase Strings supports different data-center arrangements. Its official documentation explains that organizations using the US data center should configure the corresponding US API host, for example through phrase init with a host option or the configuration file. The host matters for successful authentication and keeping operations within the intended service region.
If a team copies a configuration from an unrelated workspace, commands might fail authentication or target a different regional endpoint. This is not a problem a translator can solve by changing language text. It is an infrastructure configuration error.
Verify the host with the organization administrator before first use, particularly for regulated or geographically scoped data. Keep endpoint selection explicit in a trusted configuration. A release runbook should state the expected region so a future migration or environment rebuild does not depend on memory.
5. Handle tokens without leaking them
The Strings CLI supports access tokens and environment-based authentication, including PHRASE_ACCESS_TOKEN. The documentation also distinguishes product-specific tokens from platform tokens that may require exchange before the Strings CLI can use them. A credential that works for another Phrase service is not automatically suitable here.
Do not commit tokens in .phrase.yml or paste active values into shared commands. Use secret storage in CI and carefully scoped credentials. When debugging, record which authentication path was used without printing its secret. A logged command that contains a live token can expose the entire localization workspace.
Test token rotation with read-only operations first. Confirm that the intended account has access to the expected project. A failed authenticated call should stop the job rather than retry through a different, more privileged personal identity.
6. Separate push from pull consequences
Phrase push uploads local source or locale files according to configuration. Phrase pull downloads remote content to configured local destinations. The official documentation warns that pull overwrites local files, and push can overwrite existing remote translations when update_translations is enabled. These are state-changing operations, not just status checks.
A developer edits a French resource locally and then runs pull without saving the change. The local revision may be replaced by what the remote service currently stores. Conversely, a push configured to update translations may replace language content approved by a reviewer.
Use isolated working trees and inspect diffs before and after operations. Document which direction is authoritative in each phase. A successful command should produce a reviewable change record instead of silently choosing one copy over another.
7. Understand update_translations before enabling it
The update_translations setting controls whether incoming values update translations already in Phrase. When enabled, it can overwrite existing content. This may be appropriate for a controlled migration or an authorized correction, but it should not be treated as a default convenience.
Imagine a reviewer has improved a payment confirmation in Portuguese, but the source repository still contains an earlier wording. A routine push with remote overwrite enabled could erase the correction. The API transfer would succeed while actual communication quality moved backward.
Test the setting with one new key, one existing translated key and one reviewed sensitive message. Inspect remote results and preserve a rollback copy. Establish who authorizes bulk overwrites, what the input revision is, and which content should remain protected.
8. Treat delete_unmentioned_keys as destructive
The Phrase documentation describes delete_unmentioned_keys as an option that can remove keys not present in an uploaded source file, and warns that it should be used only when that file contains all keys for the project. A partial checkout or package-scoped source is not a valid basis for deleting an entire project’s content.
A monorepo job that uploads only frontend resources could interpret backend or mobile keys as unmentioned if cleanup is configured too broadly. Those keys might still be used daily. Losing them would create production localization gaps unrelated to translation quality.
Keep cleanup disabled for routine partial uploads. When removal is genuinely intended, inventory the complete project, prepare a deletion report and secure explicit approval. Distinguish retiring obsolete keys from accidental omission in a local checkout.
9. Recognize that uploads can be asynchronous
The official Phrase configuration guide states that uploads are processed asynchronously and supports waiting for them using the wait option. An upload command starting is therefore not proof that the remote project has finished processing every file. Automation must distinguish request acceptance from final outcome.
If a build pushes source files and immediately pulls translations, it may retrieve content from an earlier project state. The pipeline can appear green while shipping stale wording. The failure arises from sequencing, not from an incorrect dictionary translation.
Use the documented waiting behavior or equivalent completed-state checking. Capture the operation result and stop on failure. Avoid duplicate uploads caused by arbitrary timeout retries, and tie every successful operation to the source revision that was actually processed.
10. Choose locale_name and locale_code knowingly
The configuration supports placeholders such as locale_name and locale_code. The names and codes are not interchangeable in every project. An application may require one directory convention while Phrase stores another display name or standard language identifier. The documentation cautions that locale codes are not necessarily unique across project locale names.
A product has two regional review tracks for the same language code but separate names. An export path using only the shared code could overwrite one variant with the other. Conversely, a runtime might be unable to locate a file named with a human-readable display label.
Test the exact placeholder substitution for the languages in scope. Use explicit mapping where a framework expects special names. Compare output paths against the application’s locale loader before accepting the export.
11. Match globs to the correct operation
Phrase configuration supports path globbing, but push and pull do not have identical path capabilities. The documentation explains that pull needs explicit target patterns instead of arbitrary wildcard discovery. A wildcard that conveniently matches source files may not be a sensible destination definition.
For example, uploading several source files from nested folders can be appropriate, while exporting to a vague recursive wildcard creates ambiguity about where each locale belongs. If the application expects one directory per language, the configuration should state that pattern clearly.
Inspect matched push inputs and constructed pull targets in a safe test. Avoid depending on shell expansion behavior that differs across platforms. Use an explicit target file pattern with the correct locale placeholder and verify that no two locales resolve to the same destination.
12. Prevent key collisions with prefixes
Phrase Strings supports translation-key prefixes during push and corresponding prefix handling during pull. This can be useful when several source files contain identical short keys, such as title or status, that refer to different features. Prefixes preserve ownership if they are designed and applied consistently.
Two packages both define save. One saves a draft and the other saves a payment method. If the system merges both into a single unqualified key, the same translation may be reused where its meaning is wrong. A stable namespace or prefix helps avoid that collision.
Document the prefix scheme, test round-trip behavior and verify that application lookup keys match the output. Changing prefixes after translation work has accumulated should be treated as a migration, not a cosmetic tidying exercise.
13. Use tags for deliberate file separation
Tags can group translation keys and help reconstruct file organization on pull. The official configuration reference includes a tag placeholder and tag-based filtering. This is valuable when a service project stores material from several modules but the application expects distinct target files.
A customer app has separate onboarding and billing dictionaries. Tags can help export those groups back into the intended files, but only if every relevant key has the correct tag and the configuration applies it consistently. Untagged or mistagged keys can disappear from a target bundle.
Audit tag coverage before making it a release dependency. Test representative files and compare key counts against the source repository. A taxonomy change should be reviewed for build impact just as carefully as a directory rename.
14. Choose format settings for the actual parser
Different resource formats preserve different kinds of structure, comments, plurals and placeholders. The CLI configuration supports format options for supported files. A converter might produce technically valid output while altering the representation expected by the application framework.
For example, an iOS strings resource and an Android XML resource may both contain a sign-in label but require different syntax and directory conventions. A generic JSON export is not a drop-in replacement for either one without corresponding application changes.
Use the framework’s official parser or build tool to validate exported files. Test variables and plurals, not just the existence of translated words. Treat format conversion as a controlled engineering operation whose output is tested against the runtime contract.
15. Preserve placeholders without freezing grammar
An interface message may contain variable names for customers, amounts, counts or links. Translators may need to reorder those variables to produce natural target-language sentences. However, the application still expects the same valid placeholders and formatting syntax.
A checkout notification might require different grammatical forms for item counts in one language. If the runtime only understands an English singular/plural split, translating the surrounding sentence will not fix the underlying logic. A language resource must work with a locale-aware formatter.
Run automated placeholder and parser checks, then review realistic rendered examples. Include empty, singular and plural quantities, long values and mixed scripts. A syntactically valid message is a necessary but insufficient condition for clear multilingual communication.
16. Prioritize consequential text in review
Some strings are more important than others. Purchase, consent, account deletion, security warnings and cancellation messages can affect decisions and obligations. A command that downloads them says nothing about whether their target-language wording preserves the intended action.
A button labeled Continue might be inappropriate if clicking actually confirms a charge. An inaccurate translation of a renewal date may also mislead. These defects can survive every automated syntax check because the machine-readable file is structurally perfect.
Provide translators with action context, screenshots and variable explanations. Ask qualified reviewers and relevant product owners to approve high-risk content. Record difficult decisions so later source changes trigger a fresh review instead of silent reuse.
17. Understand token precedence and automation boundaries
The Phrase CLI documentation explains that configuration, environment variables and explicit command flags can supply credentials, with precedence rules. That is useful but introduces a hidden risk: a developer’s workstation might silently override the intended project token. A script can succeed with credentials that do not represent the account or permissions expected by CI.
Inspect which authentication source your workflow intends to use without printing the secret value. Keep unattended jobs independent of personal shell profiles. If an API token has access to several projects, verify the project identifier explicitly rather than assuming a successful credential check proves the correct target.
Record credential ownership, rotation requirements and the endpoint region. Avoid storing access tokens in a committed .phrase.yml. A trustworthy workflow is one in which another authorized maintainer can reproduce the operation without borrowing someone’s private workstation environment.
18. Handle regional variants as product requirements
Locale names and locale codes serve different purposes. A global application may need separate resources for Spanish-speaking markets, English regional variants or French-speaking audiences. One generic language label may hide distinctions in conventions, support procedures or customer obligations.
A form may use a different legal term in different markets while sharing much of its source text. Exporting both locales to the same filename because their code mapping was simplified can overwrite a reviewed variant. That is a path-identity defect, not a spelling problem.
Maintain a reviewed mapping from Phrase locale identities to application locale identifiers. Test fresh-session language selection, user preference changes and fallback behavior. When languages share content deliberately, document the scope and exceptions instead of silently assuming uniformity.
19. Map Android resource directories explicitly
Android resource folders use framework-specific qualifier conventions, not an arbitrary display-language name. Phrase’s configuration documentation includes locale mapping examples for Android XML. A correct mapping can connect the Phrase locale to the expected values directory, while a careless one can produce files Android never loads.
Test the default resource directory, a common language and at least one regional variant. Inspect generated directory names and confirm that the Android build includes them. Don’t infer that a readable folder name is a valid Android resource qualifier.
Build a small test app or target module with exported strings. Run it under several device locale settings, check fallback, and exercise plurals. Treat resource compilation as a required quality gate before reviewing screenshots.
20. Keep iOS strings and stringsdict responsibilities clear
Apple localization formats can contain straightforward string labels and richer plural or variation rules. A configuration that exports only the visible labels may omit required companion resources. Phrase’s documented examples show different target files for relevant Apple formats, so teams should model the application’s actual needs.
Imagine an iOS notification that says one item or several items. A translated flat string may be grammatically insufficient, while a structured rule can express quantity-sensitive forms. If the export changes the expected format, the app may fall back to a source-language message.
Use the target platform’s build and runtime tests after export. Check the supported formats, variable identifiers, plural behavior and accessibility announcements. A download appearing in the correct directory is only the start of a proper iOS localization check.
21. Build a safe multi-platform configuration
Some teams maintain web, Android and iOS clients in one release process. They may share terminology but require different resource files and formatting behavior. Phrase supports configurations with multiple source and target entries; use that flexibility to preserve each platform’s technical contract rather than forcing all outputs into one schema.
A shared label such as account settings may appear across clients, but a mobile error toast and a desktop help panel can need different length or context. Key sharing is helpful only when meaning, variable rules and usage truly align.
Review file ownership by platform and test each export with its platform’s parser. Keep a cross-platform glossary for deliberate consistency while allowing justified grammatical or layout differences. Organize the release checklist by user journeys as well as file types.
22. Account for upload-rate and download-rate behavior
Services can apply rate limits to protect infrastructure, and Phrase’s CLI documentation describes handling download rate limits. A delayed operation is not automatically a failed or completed translation job. Automation should respect the service’s behavior and ensure that downstream tasks wait for the correct output.
If a pipeline repeatedly triggers full locale downloads, rate limiting may create slow builds or retries. The wrong response is to add unbounded concurrent jobs that intensify the problem. Prefer controlled requests and clear progress logging.
Verify the exit outcome, expected file count and freshness of downloaded artifacts. Make transient service errors distinguishable from missing translations or invalid resource files. The job should either produce a traceable valid bundle or fail visibly.
23. Treat cleanup commands as reviewed operations
Deleting remote keys is materially different from importing new source messages. A cleanup action may remove translation history and context still needed by another file or release. Phrase’s documentation includes both upload cleanup tools and configuration options for unmentioned keys; use neither casually.
Before deletion, calculate which keys truly have no references in the source application. Account for dynamic lookup, server-driven experiences, email templates and old supported versions. A key absent from today’s frontend directory may remain essential to a previous mobile release.
Review a proposed deletion list with the relevant owners, preserve a backup and record the project scope. Carry out cleanup only after ensuring the source file set is complete. Technical success is not enough evidence that deletion was safe.
24. Check all keys in the intended source scope
Automated key counting can detect a broken export or an incomplete checkout. Count keys in each input namespace and expected target file, then compare with the previous approved build. A sudden loss may indicate a changed glob, wrong filter, mistaken prefix or incomplete upload.
Be careful with absolute counts. An intentional feature removal can reduce the number of keys, and a new language may have more plural variants. Use count changes as a prompt for investigation rather than making every reduction a permanent error.
Inspect representative additions, changes and removals manually. Document why each structural difference exists. This produces a more trustworthy result than relying on a CLI exit code and a single progress percentage.
25. Validate status and unverified content policies
A localized build may contain text that has not received the review level the team requires. Phrase configuration can influence whether unverified translations are included in downloads. The appropriate choice depends on the product’s risk and the organization’s sign-off policy, not merely on a desire for maximum visible coverage.
For a low-risk help tooltip, a provisional translation might be acceptable in a test build. For an account-deletion warning or subscription renewal commitment, reviewers may need explicit approval before release. A project percentage does not distinguish the consequences of the remaining uncertain strings.
Define the readiness policy in the release plan and test it with representative states. Document how missing or unverified values appear in the runtime. Never disguise an unknown translation as approved because the file structure happens to be valid.
26. Test Unicode normalization and escaping
Text can pass through YAML, JSON, XML, API responses, Git and application rendering. At each step, escaping and normalization may alter how characters behave. A resource can remain syntactically valid but display a wrong apostrophe, broken accent or unexpected direction in a mixed-script identifier.
Test languages and scripts relevant to the product, including accented Latin text, East Asian punctuation, Arabic with numerals and combining characters. Distinguish natural-language text from keys, hashes, URLs and identifiers that must remain byte-for-byte stable.
Use automated format parsers and Unicode-aware checks, then render the application on actual target environments. Verify copying, selection, font coverage and accessibility. A machine-readable resource is successful only when its intended message reaches the user intact.
27. Test right-to-left journeys rather than visual mirroring
A right-to-left interface needs correct navigation order, number presentation, mixed-direction text and usable controls. Merely switching a text container’s direction can leave order IDs difficult to copy or icons pointing the wrong way. The translated sentence may be accurate while the interaction is broken.
Run account creation, payment, search, settings and error flows with realistic Arabic or Hebrew text where those locales are supported. Include phone numbers, dates and URLs. Test both visual layout and keyboard or screen-reader behavior.
Report each defect as a wording, typography, bidirectional-layout or interaction issue. Ask translators to change the language only when meaning is the problem. Structural bugs belong in the application’s interface code and should be fixed for every affected locale.
28. Check dynamic strings against real actions
Variables and placeholders must survive export, but preserving syntax does not ensure the surrounding instruction is true. A button may say save, publish, delete or pay. The correct target-language choice depends on the actual operation and its consequences.
Consider a subscription screen where an action both confirms a plan and starts billing. If the translation only implies that a user is continuing a form, the interface can mislead even when every variable matches and the build passes.
Provide screenshots and explanations of business behavior to reviewers. Have qualified language specialists and relevant product owners confirm consequential instructions. Record decisions so source changes are reevaluated instead of automatically inheriting old approvals.
29. Plan the review of source changes
Small English edits can cause large semantic consequences. Replacing pause with cancel, optional with required, or estimate with charge can change a user’s understanding significantly. Translation memory and file synchronization cannot decide whether an existing translation remains valid.
Track changed source keys by release and label the high-risk ones. Send reviewers the old and new wording, the action context and any changed business rule. A translated segment may need complete rewriting even if the source edit changed only one word.
Keep a history of review outcomes. When the same ambiguity occurs in several languages, improve the source itself and update its context notes. Preventing future error is more useful than repeatedly repairing the same unclear message.
30. Diagnose wrong files before blaming the translation
If the app remains in English after pull, check target directories, filename placeholders, locale selection and whether the build included the exported files. If a translation is present but the interface shows an older value, investigate caching, bundle version or source-key mismatch.
If the application loads the correct value but it reads unnaturally, collect the screen and task context for a linguistic review. If the file cannot parse, inspect format options and escaping. These failures have different owners and should not trigger indiscriminate retranslation.
Use a sanitized minimal reproduction: CLI version, host region, project identity, configuration fragment, expected path, actual path and relevant result. Preserve before-and-after artifacts without exposing secrets. Fix the specific fault and add a corresponding regression test.
31. Keep a rollback plan for localized releases
A wrong translation can cause serious user confusion and sometimes requires urgent rollback. Store a known-good bundle associated with the previous application build. Ensure that its keys and formatting contracts remain compatible before restoration; a good historical file may still be incompatible with new code.
Record source revision, project, export settings, reviewed locale set and artifact hashes. Practice restoring a sample locale in a safe environment. Make the rollback owner and decision threshold clear so the response to an incident is controlled rather than improvised.
After recovery, examine the root cause and preserve evidence of the changed wording. Update glossary guidance, source descriptions or tests as necessary. A reliable release process includes learning from errors, not merely replacing the immediate file.
32. A worked Phrase Strings release
A team adds a notification informing customers when a refund has been initiated but not yet completed. Engineers update the English resource and verify that the source makes this distinction clearly. They review .phrase.yml mappings and push the source from the intended repository branch without enabling unnecessary overwrite or cleanup.
Language reviewers receive the context: money is not necessarily back in the customer’s account. The team checks regional terminology and follows the supported upload-completion behavior. It pulls approved locale files into an isolated workspace and inspects key prefixes, file paths and changed values.
The application is tested with example amounts, dates and notification delivery. Reviewers confirm that target-language wording does not promise immediate payment. The released bundle is pinned to the build and can be traced later. This is the difference between transferring text and safeguarding customer understanding.
33. The complete production checklist
Before push, inspect repository revision, project ID, API region, credentials, source patterns, locale mapping, format and key prefixes. Confirm whether update_translations, cleanup and other state-changing settings match the approved workflow. Use trusted configuration and verify upload completion.
Before pull, confirm review status, selected languages, tags, target paths, placeholders and source compatibility. Download to an isolated tree, inspect differences and run parsers, variable checks, plural tests, Unicode checks and real interface journeys. Include responsive layout and accessibility where relevant.
After release, retain the source revision, artifact hashes, reviewer sign-off, accepted exceptions and recovery procedure. Monitor concrete user problems and reproduce them before changing content widely. The professional value of Phrase Strings CLI lies in dependable, understandable localized products, not simply faster transfers.
Frequently asked questions
What configuration file does Phrase Strings CLI use?
The common workflow uses .phrase.yml to define project settings, push sources and pull targets. Keep the mapping reviewable and remove secrets before committing.
Does phrase pull overwrite local files?
Yes, the official Phrase documentation warns that pull overwrites the configured local destinations. Use a clean workspace and review changes.
When does phrase push overwrite remote translations?
Settings such as update_translations can enable replacement of existing translations. Test the intended policy and avoid broad overwrites of reviewed content.
Is delete_unmentioned_keys safe for one package in a monorepo?
Not unless the uploaded source truly represents the complete project scope. A partial file can cause valid remote keys to be removed.
What is the difference between locale_name and locale_code?
They identify locale naming in different ways, and names may not be interchangeable with codes. Verify substitution against expected application paths and regional variants.
What if the upload command returns before processing is finished?
Phrase uploads are asynchronous. Use the documented wait behavior or check completion before running downstream steps.
Why do keys from two files collide?
Identical unqualified key names can lose namespace context. Stable key prefixes and deliberate file or tag mapping help maintain separation.
Does a successful localization build guarantee accurate translation?
No. Build success checks technical structure. Human review and task-level testing are still required for meaning, tone, legal commitments and user understanding.
Official sources and further reading
For the exact current CLI behavior, consult Phrase: Using the CLI (Strings) and Phrase: Modify the CLI Configuration File. These document push, pull, authentication, upload completion, key prefixes, locale placeholders, tag-based paths and cleanup warnings. Check your installed CLI’s help and organizational settings before production writes.