Phrase offers a comprehensive and well-documented REST API (take a look at the DNA of the Phrase API if you’d like to get a better understanding of the rationale behind it). These are its key service endpoints:
- Projects: You can list, view, create or delete projects. Projects are the main modules separating logical entities. Each project has it’s own localization resources, team members, jobs, etc.
- Locales: You can list, view, create or delete different locales within each project. Locales consist of information about language tags usage, plural rules, directions rules, etc.
- Keys: You can list, view, create or delete different keys per project. Keys are the individual unique IDs used to match translation strings to the associated translation. There is also an option to add meta information such as tags or type.
- Translations. You can list, view, create or delete different translations per project. The translations contain a reference to one or more keys. Then, there is a list of available translations per locale parameter.
- Uploads: You can upload files and track their status.
- Tags: You can manage tag meta information for each key for better control and searching.
- Blacklisting keys: You can blacklist or filter out particular keys within a project.
- Versions: You can view all revisions of each translation.
Other than the core resources, there are additional endpoints that cover special operations such as Jobs, Branches, Comments, Integrations, User Management and Glossaries. As you can see for yourself, Phrase is not just an online database but rather a complete platform.
As a customer, you can consume the Phrase API in a variety of ways. For ease of use, you can always start with the UI Dashboard that you see right after logging on the main page.
However, in this tutorial, we’d like to take a look at how we can use the REST API using the provided Phrase CLI Tool and the language-specific libraries. Let’s start with the CLI Tool.
Table of Contents
Phrase CLI Tool
The CLI Tool is suitable for automation tasks and quick experimentation. We can perform most of the exposed API operations from the convenience of our favourite shell client.
To run it, you’d first need to download the client from the CLI Tool page. Once downloaded, don’t forget to make it executable if you are working on Linux or Mac.
Before we interact with the API, we need to configure our client. Run the following command in your local shell:
The <token> parameter is needed, and you can create one from your Account > Access Tokens. Once generated, enter the input and you will be asked to select a project from the list or you can create a new one…
Next, you’ll be asked to specify the default language file formats that you want to use for that project as well as their location. At the moment, Phrase supports 39 formats (still more to come):
We select the go i18n JSON format, usually used in the go-i18n library. We also discussed it this tutorial on how to go multilingual with Hugo.
Once we’re done with the configuration, we can pull the latest locales in our local environment as easy as:
If we wanted a different format, we could change it from the configuration file .phraseapp.yml topull the locales again.
Now that we’ve configured the client, we can perform some concrete operations. For example, if we want to list all our projects:
Notice: We used the jq tool to print the JSON response a bit prettier.
When we’ve updated our local translations, we can push them to the online platform so that the translations become available for other team members.
For example, add the following key to the en.all.json file:
Then, push them to the remote…
The new key will be available in the Dashboard:
If we want to access the API programatically, we can do so by using a library written in the programming language of our choice. Phrase provides several library implementations for us to use. Let’s see how we can use the Go library in practice.
First, make sure you have Go installed and configured correctly.
Then create a main.go file with the following content:
Here, we just use the Phrase client to retrieve the project list and print their names. If you configured the access token correctly, you would see the list of your projects.
The Phrase API gives you the ultimate control over the request-and-response information – useful in many scenarios, such as automation, CI and CD pipelines, translations sync and many more.
In this article, we took a look at how to take advantage of the official Phrase API using the Command Line Client and a library written in Go. If you want to explore more about Phrase and it’s related technologies, don’t hesitate to sign up for a 14-day trial period. Thanks for your time and stay put for more great tutorials!