Translation Management

Using Localization Files (Strings)

Content is machine translated from English by Phrase Language AI.

Uploading Localization Files

When uploading a file into a project, all new resources are extracted from that file and stored in a project. The uploaded file's format does not have to be the initial format set up for the project. If tags are provided for grouping resources, new keys will have those tags applied.

Some formats, such as Gettext, provide additional valuable meta information such as comments, descriptions, or information about plural forms. This information is extracted when and wherever possible and is stored along with assigned resources, allowing all valuable information provided in localization files to be saved for further use.

There are several methods for uploading files:

  • In the application, when creating a new project or by selecting Upload file in a project page

  • via API

  • via CLI

Upload Options

  • Update translations

    By default, only new content is extracted and any existing keys in a localization project are not deleted or updated; no data can be lost by uploading files. If overwriting existing data is required, replace the project resources with content from the localization file by selecting the Update translations option. Existing translations will be overwritten with the content of the uploaded localization file.

    This option is also available in the API.


    To prevent data loss, make sure that you download the latest changes to your localization file from Phrase before changing it and uploading it again with the Update translations option.

  • Update descriptions

    Select this option if updating all descriptions of the keys from the uploaded file is required. Empty descriptions will overwrite existing ones. Descriptions can contain any additional information for translators and help identify individual keys in the editor.

  • Skip upload tags

    To keep translations organized, add multiple tags to keys with meaningful labels. Select this option to prevents new keys being automatically tagged with an upload-tag.

  • Tag keys of new and updated translations

    Select this option to tag new keys and keys with updated translations automatically upon upload. This will help in distinguishing between new, updated, and old translation strings, ensuring that only the relevant keys are processed further.

    This option is also available in the API.

  • Encoding

    Specify the encoding (e.g. UTF-8) of file or have it automatically selected (automatically selected encoding may result in incorrect encoding and can be rolled back by undoing the upload).

  • Proofreading

    Skip unverification prevents the need to verify non-main language translations again when updating translations.

    Marking translations as reviewed treats all uploaded translations as reviewed. This option is available when advanced review workflow has been activated. It allows the marking of keys as being ready for being pushed to production.

Upload files via user interface

To upload files in Strings, follow these steps:

  1. Before upload, ensure that the file is formatted correctly based on type.

  2. From a project, select Upload file from the More menu.

    The Upload file page opens.

  3. Click Choose file, select a file from a directory.

    The selected file is added to the File field.

  4. Select a Format for the file.

    Suggested formats are presented first based on file type.

  5. Select a language for the file content from the dropdown list.

    If this information is not in the file itself, create a new language for the content or use an existing one.

  6. Optionally provide tags to be assigned to the new keys and any other options.

  7. Click Save.

    Content is imported and converted to keys.

Upload Summary

  • Failed upload

    If a file could not be processed properly, error details are provided to help mitigate the error.

  • Successful upload

    After the successful processing of a translation file, a summary page is presented giving an overview of the upload with buttons linking to next steps.

  • Removing keys

    To prevent accidental deletion of keys when removing keys from a localization file and uploading it again, those keys are not automatically deleted.

    To remove those keys, follow these steps:

    1. Upload the file.

    2. Click Delete and select Delete unmentioned keys.

    3. Confirm the selection.

    All keys and associated translations that were not included in the uploaded file are removed from the project.

  • Undo an upload

    Every upload triggers multiple actions and can modify a lot of data within projects and it is not possible to retract an upload.

    To remove keys that were (wrongly) introduced by an uploaded file, follow these steps:

    1. From the upload summary of the affected upload, click Delete and select Delete created keys.

    2. Confirm the selection.

    All keys and associated translations created by that upload are removed. Translations for keys that existed prior to the upload will not be removed. To remove individual translations, use the version history for each translation.

Upload Archive

From any project page, select Uploads from the More menu to access the upload archive.

The upload archive lists all historical uploads. Access detailed upload summaries of affected resources by clicking on a listed upload. All successful uploads are also presented in a project’s activity stream.

Downloading Localization Files

Language files can be downloaded from a project at any point and to any supported file format.

Files can be downloaded from the application, via API, or CLI.

Files can be downloaded from the Languages tab of any project by clicking Export (multiple files) or the More/Download button of a language.

Download Options

Download options are presented when downloading a file in the Download window with tabs for General, Advanced and Encoding.

Selecting different File formats present different options.

Use Cases

Maintaining File Structures

By default, translatable resources are stored as keys and values instead of keeping the original file structure. This allows for interchangeable file formats without being locked into one format as well as flexible grouping using tags.

Some frameworks or setups require multiple source files also requiring additional configuration.

Keeping separate files

In general, keep all translations for each language in one file. This makes resource downloads faster and more robust. Translations are kept organized in projects, so separate small files are not required.

If localization files are required to be maintained in separate files, a file-based workflow can be used by tagging the keys upon upload and using the tags as the reference when downloading translated keys back into the original files. Keys can carry multiple tags and be included in multiple files ensuring reuse and consistency. A tag-based workflow is flexible and allows for the re-organization of translation resources without having to be uploaded to projects.

Give keys unique names across all files to ensure a smooth workflow. In a key-value-based approach, a key must have the same values assigned to it in every context. Some frameworks allow the use of non-unique keys over multiple files. Some formats, such as Symfony, support message domains. These domains are detected by the filename. Keys are not automatically scoped by filename-based domains but this can be resolved by using a unique domain prefix for keys within the file.

Example CLI configuration

If working with CLI or connecting a project with a repository (e.g. GitHub, GitLab, or Bitbucket), set up a configuration file to manage uploads and downloads.

For the example, a project has several semantically named translation files for the source locale. For example: accounts.en.yml, emails.en.yml etc. These semantic names are managed through tags.

Configure the .phrase.yml to reflect the organization of the files in localization project and link them to tags in the Strings project by including the tag placeholder in the file path:

  access_token: "3d7e6598d955bfcab104c45c40af1b9459df5692ac4c28a17793"
  project_id: "23485c9c5dfb15d85b32d9c5f3d2hl54"
  file_format: yml
      - file: ./path/to/locales/<tag>.en.yml
          locale_id: "abcd1234cdef1234abcd1234cdef1234"
      # accounts
      - file: ./path/to/locales/accounts.<locale_name>.yml
          tags: accounts
      # emails
      - file: ./path/to/locales/emails.<locale_name>.yml
          tags: emails

Parameter tags can also be used in the push section instead of using the <tag>  placeholder.

The configuration creates keys with tags based on the file they came from when running a push or triggering sync from a repository. When running pull or triggering the export to the repository it groups keys into files based on their tags.

Localizing a Project for Different Regions, Clients, or Audiences

A product, website, or app is translated into a number of different languages but in some cases, localization is not just the chosen language, but different versions within one language.

Further distinction is required if:

  • A product has a different branding in regions where the same language is spoken.

  • A product is used by different clients who want to use a white label solution.

  • Language variants such as simple, formal or informal are required.

Localizing a static product

If a product is fully developed and rarely updated, a separate version of the product can exist within a project.

  • If a single output or a short-term project:

    Create a branch, work exclusively on that branch for the duration of the project, and delete the branch when complete.

  • If a long-term project:

    Maintain a duplicate of the existing project. This allows the inviting and working with clients in the same organization by only providing access to their project(s), leaving other projects hidden to them.

Localizing a project with continuous updates

If a product is constantly updated with new content (keys), applying those updates to multiple projects and keeping them synchronized is difficult. Use dedicated languages within a project to maintain them.

Language codes following the ISO standard (e.g. en-US) don't have to be unique, so many versions of the same language can be created within a project. Distinguish between regions, clients, or audiences by using a unique language name.

When setup, any newly introduced key in the default locale would show up as untranslated in the other languages and be localized accordingly. If working with a client and their own translator(s), specifically assign them to only be able to edit their language versions by updating the language access in their user profile or the project user management.

Set up parallel localization processes with jobs and review workflows within the same project. This flexibility also extends to uploading and downloading language files or automated processes via API.

Was this article helpful?

Sorry about that! In what way was it not helpful?

The article didn’t address my problem.
I couldn’t understand the article.
The feature doesn’t do what I need.
Other reason.

Note that feedback is provided anonymously so we aren't able to reply to questions.
If you'd like to ask a question, submit a request to our Support team.
Thank you for your feedback.