Semi-automated Text Translator for Websites and Apps
attranslateis a semi-automated tool for "synchronizing" translation-files.
attranslateis optimized for fast and smooth rollouts in hectic project environments, even if you already have many translations. Optionally,
attranslateworks with automated translation-services. For example, let's say that a translation-service achieves 80% correct translations. Thanks to
attranslate, a quick fix of the remaining 20% may be faster than doing everything by hand. Other than that,
attranslatesupports purely manual translations and even file-format-conversions without changing the language.
In contrast to paid services, a single developer can integrate
attranslatein a matter of minutes. In contrast to many other tools,
attranslatecan operate on the very same translations-files that you are already using. This is possible because
attranslateoperates on your file in a surgical way, with as little changes as possible. See tools comparison for an overview about translation-tools.
attranslateis designed to translate any website or app with any toolchain.
attranslateworks for i18n/JavaScript-frameworks/Android/iOS/Flutter/Ruby/Jekyll/Symfony/Django/WordPress and many other platforms. To make this possible,
attranslatesupports the following file formats:
attranslaterecognizes that automated translations are not perfect. Therefore, whenever you are unhappy with the produced results,
attranslateallows you to simply overwrite texts in your target-files.
attranslatewill never ever overwrite a manual correction in subsequent runs.
attranslateis capable of detecting outdated translations. Normally, overwriting outdated translations helps to ensure the freshness of translations. However, in hectic project environments, it might be easier to leave outdated translations as-is. Therefore,
attranslateleaves outdated translations as-is unless you explicitly configure it to overwrite them.
attranslatesupports the following translation-services:
manual: Translate texts manually by entering them into
attranslate.
sync-without-translate: Does not change the language. This can be useful for converting between file formats, or for maintaining region-specific differences.
If some texts have already been translated, then
attranslatewon't translate them again. This does not only speedup your workflow, but also saves cost for paid translation-services.
Although (some) humans have excellent translation-skills, humans are notoriously bad at detecting "trivial" mistakes like outdated, missing, stale or duplicate translations. In contrast,
attranslatedetects such "trivial" mistakes with 100% reliability.
Translating a single file is as simple as the following line:
attranslate --srcFile=json-simple/en.json --srcLng=en --srcFormat=nested-json --targetFile=json-simple/de.json --targetLng=de --targetFormat=nested-json --service=manual
If you have multiple target-languages, then you will need multiple calls to
attranslate. You can write something like the following script to avoid unnecessary duplication:
# This example translates an english JSON-file into spanish, chinese and german. It uses Google Cloud Translate. BASE_DIR="json-advanced" SERVICE_ACCOUNT_KEY="gcloud/gcloud_service_account.json" COMMON_ARGS=( "--srcLng=en" "--srcFormat=nested-json" "--targetFormat=nested-json" "--service=google-translate" "--serviceConfig=$SERVICE_ACCOUNT_KEY" "--cacheDir=$BASE_DIR" "--matcher=i18next" )Run "npm install --global attranslate" before you try this example.
Use "--overwriteOutdated=false" if you introduce attranslate into a hectic project-environment,
or if you expect that some project collaborators won't even use attranslate because they have no time for "learning" it.
attranslate --overwriteOutdated=false --srcFile=$BASE_DIR/en/fruits.json --targetFile=$BASE_DIR/es/fruits.json --targetLng=es "${COMMON_ARGS[@]}"
Use "--overwriteOutdated=true" if you want to prevent outdated translations.
attranslate --overwriteOutdated=true --srcFile=$BASE_DIR/en/fruits.json --targetFile=$BASE_DIR/zh/fruits.json --targetLng=zh "${COMMON_ARGS[@]}"
Use "--overwriteOutdated=true" if you have no clue about the target-language and no capacity for manual reviews.
attranslate --overwriteOutdated=true --srcFile=$BASE_DIR/en/fruits.json --targetFile=$BASE_DIR/de/fruits.json --targetLng=de "${COMMON_ARGS[@]}"
Similarly, you can use
attranslateto convert between file-formats. See sample scripts for more examples.
Run
attranslate --helpto see a list of available options:
Usage: attranslate [options]Options: --srcFile The source file to be translated --srcLng A language code for the source language --srcFormat One of "flat-json", "nested-json", "yaml", "po", "xml", "ios-strings", "arb", "csv" --targetFile The target file for the translations --targetLng A language code for the target language --targetFormat One of "flat-json", "nested-json", "yaml", "po", "xml", "ios-strings", "arb", "csv" --service One of "manual", "sync-without-translate", "google-translate" --serviceConfig supply configuration for a translation service (either a path to a key-file or an API-key) --cacheDir The directory where a translation-cache is expected to be found (default: ".") --matcher One of "none", "icu", "i18next", "sprintf" (default: "none") --overwriteOutdated If true, overwrite outdated translations in subsequent runs (default: "false") --keySearch A regular expression to replace translation-keys (can be used for file-format conversions) (default: "x") --keyReplace The replacement for occurrences of keySearch (default: "x") -v, --version output the version number -h, --help display help for command
Firstly, ensure that nodejs is installed on your machine. Once you have
nodejs, you can install
attranslatevia:
npm install --global attranslate
Alternatively, if you are a JavaScript-developer, then you should install
attranslatevia:
npm install --save-dev attranslate
Next, you should write a project-specific script that invokes
attranslatefor your specific files. See sample scripts for guidance on how to translate your project-specific files.
If you use
attranslatewith an automated translation-service, then you need to configure an API-key. API-keys can be obtained for free, but you might need to register an account. See service config for guidance on how to obtain API-keys for specific services.
Once you have an API-key, pass your API-key to
attranslatevia the
--serviceConfigflag.
:warning: For many projects,
attranslateworks out of the box without configuring any matchers. Therefore, we recommend skipping this section unless you encounter unexpected problems that are hard to fix manually.
Many websites/apps use interpolations to insert dynamic values into translations. For example, an interpolation like
Your name is {{name}}might be replaced with
Your name is Felix.
To help with interpolations,
attranslateprovides so-called matchers. A matcher replaces interpolations with placeholders before they are sent to a translation service.
attranslateoffers the following matchers for different styles of interpolations:
{name}.
{{name}}.
%s.
You can select a matcher with the
--matcheroption.
:warning: If
--overwriteOutdatedis set tofalse, thenattranslatedoes not generate any translation-cache.
The purpose of the translation-cache is to detect outdated translations, such that outdated translations can be overwritten in subsequent runs. The translation-cache consists of
attranslate-cache-*-files. It is allowed to delete a translation-cache at any time. However, to make it work smoothly, you should put your
attranslate-cache-*-files under version control.
To detect common mistakes like missing translations, it is advisable to run
attranslatevia continuous integration (CI). For example, the command
git diff --exit-codecan be used to trigger a CI failure whenever a file has been modified by
attranslate.