Polyglot is a localization tool that simplifies the translation process of your iOS mobile application. Our SDK can process .strings files and provide fast and accurate translations using AI-powered technology, as well as manual ones a bit later. By using Polyglot, you can easily translate your app into multiple languages and reach a wider audience with minimal effort.
The tool uses English localization as the basis for translations.
- Vocabulary
- Integration options
- Adding a new localization
- Support
- Are texts translated by AI or by a human?
- How fast will it work?
- In which file do I need to write strings for translation?
- Should I use Base localization or English?
- Should I commit translations to the git history?
- How I stop Polyglot from translating specific strings?
- How I can limit the translation length?
- How I can add a comments that will be ignored by Polyglot?
- License
To use Polyglot, you will need or may need the following parameters:
| Term | Description | Where to get | Default value |
|---|---|---|---|
<your_token> |
The API token provided by Polyglot. | Use the official website to generate the API token for your tariff plan. | — |
<your_bundle_id> |
The product bundle identifier of the Xcode project. | 1) Open your Xcode project 2) In the Project Navigator select the project itself 3) Select the main project target 4) In the General tab a bundle identifier is under the Identity section. |
— |
<workdir_path> |
The path to the directory to search files to be localized. | The path to the place where the tool will recursively search for your localization files, so you can specify any path along which it will be convenient to search for them. However, keep in mind that the path should not point to a directory containing several projects at once. | The directory from which the script is run. When running from the Xcode build phase, it takes the value of the $PROJECT_DIR environment variable. |
<files_to_translate> |
A comma-separated list of file names to translate. | Here you need to list the file names for translation. For example, it can be "Localizable.strings" or "Localizable.strings,InfoPlist.strings". Keep in mind that these are names, not paths. |
Localizable.strings |
These terms will be used further in integration options.
To install Polyglot, add the following line to your Podfile:
pod 'PolyglotRocks'Then, run pod install to install the library.
To use Polyglot in your Xcode project, before the build phase named Copy Bundle Resources, add a new one with the following command:
# Somewhere before the Copy Bundle Resources phase
"${PODS_ROOT}/PolyglotRocks/bin/polyglot" <your_token>
Optionally, you can set the -f parameter to specify the file names for translation (see vocabulary for more details):
"${PODS_ROOT}/PolyglotRocks/bin/polyglot" <your_token> -f <files_to_translate>Now you can try adding languages to the project. For more details, you can go through a tutorial on using Polyglot with an Xcode project.
To run Polyglot on your local machine with Xcode, you can use a special script via cURL. To do this, before the build phase named Copy Bundle Resources, add a new one with the following command:
# Somewhere before the Copy Bundle Resources phase
/bin/bash -c "$(curl -fsSL https://polyglot.rocks/run.sh)" - <your_token>This script will download the latest version of Polyglot if needed and then will execute it at every build of your project using Xcode.
Optionally, you can set the -f parameter to specify the file names for translation (see vocabulary for more details):
/bin/bash -c "$(curl -fsSL https://polyglot.rocks/run.sh)" - <your_token> -f <files_to_translate>Now you can try adding languages to the project. For more details, you can go through a tutorial on using Polyglot with an Xcode project.
Alternatively, you can run Polyglot on your local machine as a regular tool in the terminal. Keep in mind that in this case you probably need to manually set the PRODUCT_BUNDLE_IDENTIFIER environment variable that Xcode usually deals with. For example, like this:
PRODUCT_BUNDLE_IDENTIFIER=<your_bundle_id> /bin/bash -c "$(curl -fsSL https://polyglot.rocks/run.sh)" - <your_token> -p <workdir_path> -f <files_to_translate>
<workdir_path>and<files_to_translate>are optional parameters here.
Now you can try adding languages to the project.
The Polyglot GitHub Action allows you to easily automate the localization process for your projects in CI/CD pipeline. Please note that this action requires Linux-based runners, as it uses Docker under the hood. Here is an example workflow for using the action in your GitHub Actions:
name: Polyglot
on:
pull_request:
branches:
- main
jobs:
translate:
# Polyglot GitHub Action is designed to work on Linux-based runners.
runs-on: ubuntu-latest
steps:
# 1. Checkout latest version of your changes.
- uses: actions/checkout@v3
with:
fetch-depth: 0
ref: refs/heads/${{ github.event.pull_request.head.ref }}
# 2. Run Polyglot
- uses: clickcaramel/PolyglotRocks@main
with:
# The API token provided by Polyglot.
token: <your_token>
# The product bundle identifier of the Xcode project.
bundle_id: <your_bundle_id>
# The path to the directory to search files to be localized (optional).
path: <workdir_path>
# A comma-separated list of names of .strings files that are being translated (optional).
files_to_translate: <files_to_translate>
# (optional) Keep this step if you need to commit changes to the git history.
- name: Commit Changes
run: |
git config --local user.name "Polyglot"
git config --local user.email "[email protected]"
git commit -a -m "chore: update translations" || echo "Nothing to commit"
git pushIf you want to use the tool on runners with other operating systems, then you can embed its cURL version in the workflow:
name: Polyglot
on:
pull_request:
branches:
- main
jobs:
translate:
# You can use this option on a runner where there is no docker, but there is curl.
runs-on: macos-latest
steps:
# 1. Checkout latest version of your changes.
- uses: actions/checkout@v3
with:
fetch-depth: 0
ref: refs/heads/${{ github.event.pull_request.head.ref }}
# 2. Run Polyglot via cURL
- name: Run Polyglot
run: |
export PRODUCT_BUNDLE_IDENTIFIER=<your_bundle_id>
/bin/bash -c "$(curl -fsSL https://polyglot.rocks/run.sh)" - <your_token> -p <workdir_path> -f <files_to_translate>
# (optional) Keep this step if you need to commit changes to the git history.
- name: Commit Changes
run: |
git config --local user.name "Polyglot"
git config --local user.email "[email protected]"
git commit -a -m "chore: update translations" || echo "Nothing to commit"
git pushNow you can try adding languages to the project.
Polyglot can also be used with Docker. To get started, pull the image from the repository by running the following command:
docker pull ghcr.io/clickcaramel/polyglot-rocks:latestOnce you have pulled the image, you can run a Docker container with the following command:
docker run --rm \
--env "TOKEN=<your_token>" \
--env "PRODUCT_BUNDLE_IDENTIFIER=<your_bundle_id>" \
--env "FILES_TO_TRANSLATE=<files_to_translate>" \
--volume "<workdir_path>:/home/polyglot/target" \
ghcr.io/clickcaramel/polyglot-rocks:latest
<files_to_translate>is an optional parameter here.
Keep in mind:
- Docker uses absolute paths in volume mappings.
- You cannot omit the
<workdir_path>parameter here, since you must explicitly specify volume for Docker.
To add a new localization, follow these steps:
- Open your Xcode project.
- Select your project in the project navigator.
- Click on the "Info" tab.
- Scroll down to the "Localizations" section.
- Click on the "+" button to add a new localization.
- Select the language and region you want to add.
- Xcode will generate a new
.stringsfile for the new localization.
Now Polyglot will see this file and translate your lines from English language to the new one too.
Both.
Polyglot provides an opportunity to quickly get AI-powered translations of your localization strings, and then use experts to check and improve translations.
Depends on the number of strings.
Each line is translated separately in order to conveniently maintain the context and avoid repeated translation. Therefore, if you are using the Xcode build phase and you have quite a lot of lines, then this may slow down your build. To avoid this, we recommend using CI/CD for a large number of localization strings.
PolyglotRocks for translation takes as a basis the lines that are written in the .strings file (by default, Localizable.strings) and lie in the en.lproj directory (English localization). Then it translates them into other languages, the support of which (or the presence of the corresponding .lproj directory) is in the project.
Since the tool uses English localization as the basis for translations, you can initially keep other localization files empty, and it will fill them in by itself.
For more details, you can go through a tutorial on using Polyglot with an Xcode project.
PolyglotRocks considers only the "English" localization (en.lproj) as the source for translations into other languages. Hence, the content of Base.lproj is ignored by the tool.
We suggest not committing translations to the git history to avoid conflicts between git branches. Instead, translations should be used only for deployment. Here's how to avoid committing translations:
- Leave all localization files except the base one clean and do not modify them.
- Launch Polyglot only before deploying to the production or development environment, so not to commit changes to the git history.
You may add // polyglot:disable:this comment at the end of a line containing the string you don't want Polyglot to touch:
"CUSTOM_STRING" = "this value will not be touched by Polyglot"; // polyglot:disable:thisYou can use // polyglot:max_length:<number> comment before the line. As an argument, specify the maximum length of the translation in characters. For example:
// polyglot:max_length:15
"Saved successfully" = "Saved successfully";AI will take this into account when translating, but there is no guarantee that it will fulfill the condition. The human will try to translate with the condition in mind. If he does not succeed, he will leave a comment along with the translation option as to why it is not possible. You will see the comment at the end of the translation line:
"CUSTOM_STRING" = "Personnalisé"; // translator comment: "Condition is too hard"You can use triple slash for that:
/// comment for my teammates
// description of the string
"dev_comments" = "Comments for developers";'Also comments for Xcode that starts with MARK:, FIXME: or TODO: will be ignored
We hope this helps! If you have any other questions, please do not hesitate to ask.
Polyglot is released under the Apache-2.0 license. See LICENSE for details.