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.
Files can be uploaded in the application, via API, or CLI.
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 theoption. Existing translations will be overwritten with the content of the uploaded localization file.
This option is also available in the the API.
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.
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.
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).
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.
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 theoption.
To upload files in Strings, follow these steps:
Before upload, ensure that the file is formatted correctly based on type.
From a project, select Upload file from the menu.
Click Choose file, select a file from a directory.
The selected file is added to thefield.
Select afor the file.
Suggested formats are presented first based on file type.
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.
Optionally provide tags to be assigned to the new keys and any other options.
Content is imported and converted to keys.
If a file could not be processed properly, error details are provided to help mitigate the error.
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.
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:
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:
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.
From any project page, selectfrom the 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 Export (multiple files) or the More/Download button of a language.tab of any project by clicking
Download options are presented when downloading a file in thewindow with tabs for , and .
Selecting differents present different options.
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:
emails.en.yml etc. These semantic names are managed through tags.
.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:
phrase: access_token: "3d7e6598d955bfcab104c45c40af1b9459df5692ac4c28a17793" project_id: "23485c9c5dfb15d85b32d9c5f3d2hl54" file_format: yml push: sources: - file: ./path/to/locales/<tag>.en.yml params: locale_id: "abcd1234cdef1234abcd1234cdef1234" pull: targets: # accounts - file: ./path/to/locales/accounts.<locale_name>.yml params: tags: accounts # emails - file: ./path/to/locales/emails.<locale_name>.yml params: tags: emails
Parameter tags can also be used in the push section instead of using the
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.
A product, website, or app is translated into a number of different languages but in some cases, localization isn't 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.