POEditor
Whenever you get the chance to automate something to avoid repetitive manual work, go for it, because it will save you a lot of time and boost your productivity. That being said, let’s cut to the chase: the purpose of this article is to show you how to automate your localization workflow with the POEditor API. For this, we’ll go through a simple step by step guide. You’ll learn how to send your language data to POEditor and how to pull the translated work back into your software.
Knowledge of a programming language is required (any will do), but we’ll focus on the requests you need to make to the API.
All the information about the API is in the API Reference.
Before starting the actual work, get an API token from your POEditor account. You can find it in Account Settings > API Access.
Project setup
The first step is to create a project. Note that you need to do this only once and that you can also use the interface. It’s probably faster anyway.
Create a project:
curl -X POST https://api.poeditor.com/v2/projects/add \
-d api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-d name="Quick Guide"
You’ll need a name for this. The response will contain the new project ID (the item key from your response JSON). You’ll need this on future requests, so the system knows what project you’re referring to. The answer will look like this:
{"response":{"status":"success","code":"200","message":"Project created."},
"result":{"project":{"id":76197,"name":"Quick Guide","description":"","public":0,"open":0,
"reference_language":"","terms":0,"created":"2017-06-21T12:22:59+0000"}}}
Next step: add some languages to the project. Let’s say your software’s in English and you need to translate it in French and Spanish.
curl -X POST https://api.poeditor.com/v2/languages/add \
-d api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-d id="76197" \
-d language="en"
For this, you need the project ID you got earlier and the language code. Check out a list of language codes here or make a request to the API to get the full list using the available languages method.
A success response will show up:
{"response":{"status":"success","code":"200","message":"Language was added: English [en]"}}
Do the same for “fr” and “es” language codes. Afterwards, you can check like this:
curl -X POST https://api.poeditor.com/v2/languages/list \
-d api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-d id="76197"
The response should be:
{"response":{"status":"success","code":"200","message":"OK"},"result":{"languages":
[{"name":"English","code":"en","translations":0,"percentage":0,"updated":""},
{"name":"French","code":"fr","translations":0,"percentage":0,"updated":""}]}}
You’re all set for now.
Push data to POEditor
Now you should populate the project with the data from your existing language file. To do that, you’ll need the path to the exiting language file and the ID of the project.
curl -X POST https://api.poeditor.com/v2/projects/upload \
-F api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-F id="76197" \
-F updating="terms_definitions" \
-F language="en" \
-F file=@"/var/www/html/en.properties"
The response will look like this:
{"response":{"status":"success","code":"200","message":"OK"},"details":{
"terms":{"parsed":105,"added":105,"deleted":0},
"definitions":{"parsed":105,"added":105,"updated":0}}}
You can see the system found 105 terms and 105 translations and it added all of them (because the project is empty at this point). If you run that request again, you’ll get in the response ‘parsed: 105’ and ‘added: 0’ (because they’re already in the project).
Translation can begin now. Add your contributors, translate the project yourself, order human translations… your pick. Note that if your language file is label based, you can set a reference language (in this case English) so your translators don’t see labels but texts in a human language. This can be done from Project Settings in the interface or using the “project update” method from API:
curl -X https://api.poeditor.com/v2/projects/update \
-d api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-d id="76197" \
-d reference_language ="en"
Pull translated languages from POEditor
After the translations are completed, you need to request the language files and save / update them in your software.
curl -X POST https://api.poeditor.com/v2/projects/export \
-d api_token="e9eccebeccfr9wed638eb35f5e2d5600" \
-d id="76197" \
-d language="fr" \
-d type="properties"
In the response you’ll get a temporary link (it expires after 10 minutes) to a file with the contents you requested:
{"response":{"status":"success","code":"200","message":"OK"},
"result":{"url":"https:\/\/api.poeditor.com\/v2\/download\/file\/752e699a355e829a710623a37dd051c3"}}
It’s up to you how you get and save the content, with whatever naming you’re using in your project. Add this in a foreach with all the languages in your project and you’ll get your fully automated pull script.
That’s it. You can even set a cronjob once a day and you’ll have updated language files automatically, without moving a finger.
If you host your code on GitHub, Bitbucket or GitLab, it’s even easier and you don’t have to write any code at all.