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
-
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 option. Existing translations will be overwritten with the content of the uploaded localization file.
This option is also available in the API.
Note
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 option.
-
Enter a unique identifier (e.g. the file path) to prepend to the uploaded translation key names. Use a meaningful prefix related to the project or file to keep key names organized.
For example, an imported key
hello_worldwith the prefixproject_will result in the keyproject_hello_world.The translation key prefix ensures that keys are matched against existing ones to avoid collisions across different projects or files.
This option is also available in the API and CLI interface.
-
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.
-
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.
-
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 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.
The page opens.
-
Click Choose file, select a file from a directory.
The selected file is added to the field.
-
Select a for 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.
-
Click Save.
Content is imported and converted to keys.
-
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. Click the upload tag to open the file in the editor.
-
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:
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.
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 tab of any project by clicking Export (multiple files) or the More/Download button of a language.
Download options are presented when downloading a file in the window with tabs for , and .
Selecting different s present different options. For more details, refer to the relevant article about the specific file format.
-
If a translation key prefix has been added upon file upload, select this option in the tab to remove the prefix from the names of the exported translation keys:
-
Enter the prefix to download all keys, and remove the specified prefix where possible.
Important
This may create duplicate key names if other keys share the same name after the prefix is removed.
-
If required, select to download only the translation keys containing the specified prefix, and remove the prefix from the downloaded file.
This option is also available in the API and the CLI interface.
-
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:
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 <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.
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.