👀 Introduction to Localazy API 🔗

Localazy is a web-based translation management system and a continuous localization platform that makes translating software, websites, and other digital content into multiple languages easy.

The Localazy API allows users to connect their projects to the Localazy platform and automate their localization, push new source texts to Localazy, fetch translations, and interact with various features and aspects of Localazy programmatically.

When should you use the API instead of the CLI? 🔗

You can integrate your project with Localazy in various ways. Apart from manual file uploads and our native integrations (for example, Strapi Localization Plugin or the Figma Plugin), you can also use Localazy CLI to handle content transfers programmatically.

Both options have their advantages (e.g., CLI is arguably better for handling static files) but let's quickly discuss why using API is a good idea.

  1. The API allows you to build a native Localazy integration into your product.
  2. The Localazy API is great for handling automated content transfers and can tap into other Localazy features such as Screenshots, Glossary, and others programmatically.
  3. The API approach is the most adaptable because it adds new possibilities and allows you to create your own logic to use it effectively.
  4. Localazy API is preferred for custom integrations and workflows.

🏁 Before you start 🔗

To follow this guide, you need a free Localazy account and a basic understanding of how REST API works and how to use Postman for API testing.

Limitations

Please bear in mind that the Localazy API also has some limitations in terms of requests and the max size of content it can handle per request. You can learn more in the API documentation.

🚩 Getting Started with the Localazy API 🔗

The Localazy API employs standard HTTP response codes, authentication, verbs, and resource-based URLs. All endpoints are relative to the base URL, https://api.localazy.com. The documentation for all endpoints is available here.

You must authenticate your request in order to access all endpoints because they are protected by access tokens.

Integration of Localazy API 🔗

In this section, we'll create an online reading application where users can see a list of their favorite books in their preferred language. To handle content translation, we will make use of the Localazy API.

article-image
This is the front-end UI for the reading web application, built with React.
As we'd like to focus on localization in this article, so you can get the front-end code in the GitHub repository.

Create a new Localazy project

Log in and create a new project in Localazy as shown below, in the Localazy dashboard.

article-image

In the screenshot below, you can see I named my project reading-app. Follow similarly and call your project how you want, then click Create New Project to continue.

article-image

After creating a project, we are directed to a new page where we can choose the type of integration.

article-image

Select the API integration from the list and follow the guidelines.

article-image

We need to obtain the access token from the Developer Console before we can begin using the Localazy API. This must be included in the authorization header for all API requests.

Authorization: Bearer {{token}}

The project token is available in the developer console. This token gives you access to a single project in Localazy and grants read and write access.

📋 Get Project ID 🔗

The first step is to obtain the ID of the newly created project. Navigate to Postman and make a GET request to the URL https://api.localazy.com/projects

Remember to include the token in the authorization header for the request.

The response is similar to the following code snippets:

[
   {
       "id": "_a7922645342385287434",
       "orgId": "_a8097378946439832685",
       "name": "reading-app",
       "slug": "reading-app",
       "image": "",
       "url": "https://localazy.com/p/reading-app",
       "description": "",
       "type": "restricted",
       "tone": "not_specified",
       "role": "owner",
       "sourceLanguage": 85
   }
]

📑 Import content to Localazy using API 🔗

The next step is to import content from our reading app project into Localazy using the project ID. The content to be translated should be saved in a JSON file with a key and value format. You can view the content to be translated in the public/locales/en/translation.json file of the repository linked earlier.

The request body of the API call is similar to this:

{
 "files": [
   {
     "name": "translation.json",
     "content": {
     "type": "json",
       "en": {
           "title": {
               "title1": "The Psychology of Harry Potter",
               "title2": "Quinn",
               "title3": "A Thief in the Night",
               "title4": "Demon Dentist",
               "title5": "Why We Sleep",
               "title6": "Invisible Women"
           },
           "author": {
               "author1": "Neil Mulholland",
               "author2": "Trevor Birney",
               "author3": "Life and Death in the Vatican",
               "author4": "David Walliams",
               "author5": "Matthew Walker",
               "author6": "Caroline Criado Perez"
           },
           "description": {
                "description1": "Harry Potter has provided a portal to the wizarding world for millions of readers, but an examination of Harry, his friends and his enemies will take us on yet another journey",
        "description2": "This is the gripping inside story of Ireland's bankrupt billionaire, Sean Quinn, who went from rags to riches before gambling it all on Anglo-Irish Bank shares and became the world's biggest personal loser of the economic.",
        "description3": " A model of investigatory journalism and a small masterpiece of the genre.” Anthony Burgess On the eve of September 28, 1978, John Paul I died unexpectedly apparently of a heart attack after ",
        "description4": " Darkness had come to the town. Strange things were happening in the dead of night. Children would put a tooth under their pillow for the tooth fairy, but in the morning they would wake up to find a dead slug",
        "description5": "Sleep is one of the most important but least understood aspects of our life, wellness, and longevity. An explosion of scientific discoveries in the last twenty years has shed new light on this fundamental aspect of our lives.",
        "description6": "Winner of the 2019 Royal Society Science Book Prize Shortlisted for the 2019 Financial Times and McKinsey Business Book of the Year Award Data is fundamental to the modern world."
           }
       }
     }
   }
 ]
}

The file's id should be returned as the response.

Translate your imported content with Localazy 🔗

After importing the file, the translation will be handled in the localazy dashboard. We can add languages here for translations. We want to add French (fr), Spanish (es), and Czech (cs) as well.

article-image

We can view the imported file in the source language (English).

article-image

You can then use the Localazy machine translation feature to translate all keys in our imported content. In an actual project, you can also invite translators to help you or order professional translation services directly inside the platform.

article-image

At this stage, we have handled translation across all languages.

article-image

📥 Download translations via API 🔗

We want to download the French, Czech, and Spanish translated files and store the contents in a public/locales/fr/translation.json, public/locales/cs/translation.json, and public/locales/es/translation.json files respectively.

We can also configure the shared/i18n/i18n.js to include the supported languages in the application.

Now, we are ready to download all translated files into our reading-app project. Localazy API has an endpoint to retrieve all the files in your project as a GET request to https://api.localazy.com/projects/{projectId}/files

All files with their ids are fetched, and the content of the files can be downloaded with the Localazy API download endpoint. Send a POST request to https://api.localazy.com/projects/{projectId}/files/{fileId}/download/{language}

The Spanish translation of the reading-app project can be seen below:

{
    "author": {
        "author1": "Neil Mulholland",
        "author2": "Trevor Birney",
        "author3": "Vida y muerte en el Vaticano",
        "author4": "David Walliams",
        "author5": "Matthew Walker",
        "author6": "Caroline Criado Pérez"
    },
    "description": {
        "description1": "Harry Potter ha proporcionado un portal al mundo mágico para millones de lectores, pero si analizamos a Harry, sus amigos y sus enemigos emprenderemos otro viaje: a través de la psique de los muggles (¡y del mago!) mente.",
        "description2": "Esta es la apasionante historia interna del multimillonario irlandés en quiebra, Sean Quinn, que pasó de la pobreza a la riqueza antes de apostarlo todo por las acciones del banco angloirlandés y se convirtió en el mayor perdedor personal del mundo tras el colapso económico de 2008.",
        "description3": " Un modelo de periodismo de investigación y una pequeña obra maestra del género». —Anthony Burgess La víspera del 28 de septiembre de 1978, Juan Pablo I murió inesperadamente —al parecer de un ataque al corazón— tras un reinado de solo 33 días.",
        "description4": " La oscuridad había llegado a la ciudad. Ocurrían cosas extrañas a altas horas de la noche. Los niños ponían un diente debajo de la almohada para el hada de los dientes, pero por la mañana se despertaban y encontraban una babosa muerta",
        "description5": "El sueño es uno de los aspectos más importantes pero menos entendidos de nuestra vida, bienestar y longevidad... Una explosión de descubrimientos científicos en los últimos veinte años ha arrojado nueva luz sobre este aspecto fundamental de nuestras vidas.",
        "description6": "Ganador del premio del Libro de Ciencias de la Royal Society 2019, preseleccionado para los premios Financial Times y McKinsey Business Book of the Year 2019, los datos son fundamentales para el mundo moderno."
    },
    "title": {
        "title1": "La psicología de Harry Potter",
        "title2": "Quinn",
        "title3": "Un ladrón en la noche",
        "title4": "Dentista demoníaco",
        "title5": "Por qué dormimos",
        "title6": "Mujeres invisibles"
    }
}

The updated UI showing the translated content can be seen below:

article-image
Czech (cs) translated page
article-image
Spanish (es) translated page
article-image
French (fr) translated page

✒️ Update the source key using API 🔗

A source key is a single key:value pair in the source language JSON file. When you try to list all contents in a file in the English language, you can easily see all of the source keys.

We can view all the source keys in a file by navigating to Postman and making a GET request to the URL https://api.localazy.com/projects/{projectId}/files/{fileId}/keys/en

You should get a response similar to this:

{
   "keys": [
       {
           "id": "_a7917183974514294240", //This is a source key id
           "key": [
               "title",
               "title2"
           ],
           "value": "Quinn",
           "vid": -7917183974514294239
       },
       {
           "id": "_a7917183974514294228",
           "key": [
               "author",
               "author2"
           ],
           "value": "Trevor Birney",
           "vid": -7917183974514294227
       },
       {
           "id": "_a7917183974514294216",
           "key": [
               "description",
               "description2"
           ],
           "value": "This is the gripping inside story of Ireland's bankrupt billionaire, Sean Quinn, who went from rags to riches before gambling it all on Anglo-Irish Bank shares and became the world's biggest personal loser of the economic collapse of 2008.",
           "vid": -7917183974514294215
       },
       {
           "id": "_a7917183974514294210",
           "key": [
               "description",
               "description5"
           ],
           "value": "Sleep is one of the most important but least understood aspects of our life, wellness, and longevity ... An explosion of scientific discoveries in the last twenty years has shed new light on this fundamental aspect of our lives.",
           "vid": -7917183974514294209
       }
   ]
}

A project's source key can be updated by sending a PUT request to the URL https://api.localazy.com/projects/{projectId}/keys/{keyId} where projectId is the id of the project and keyId is the id of the key whose properties are being updated.

We can update the source key for the title key id so it can be hidden from being translated.

Before you continue reading, I recommend you read more about the different states source keys can be in: What is the difference between hidden and deprecated source keys?

The request body includes the following snippets:

{
 "deprecated": -1,
 "hidden": true,
 "comment": "This title1 key will be hidden from translation",
 "limit": 100
}
  • The deprecated field - denotes a value where a version greater than the value deprecates the key, and it can be set to -1 to indicate that the key is not deprecated.
  • The hidden field - is a boolean value that indicates whether or not the key should be translated in Localazy.
  • The comment field - contains a comment that is visible to translators.
  • The limit field - specifies a translation limit for that key, which can be disabled by setting its value to -1.

The response returns true as a value.

We can access the Localazy dashboard and see something like this.

article-image

🚮 Delete the source key using API 🔗

The source key can also be removed by sending a DELETE request to https://api.localazy.com/projects/{projectId}/keys/{keyId}

The result is returned as a true value by the response.

We can access the Localazy dashboard, and this key is no longer visible because it has been deleted.

📖 Add Glossary terms using API 🔗

The Glossary ensures that translations are precise and consistent, which is critical for successful app localization. This article contains a more detailed explanation of the glossary.

Glossary terms can be added via API using the URL: https://api.localazy.com/projects/{projectId}/glossary

In our project, for example, we want the author's name to be consistent throughout the project, so we would include the author's name as a term. The request body looks like the following:

{
   "description": "The Author Name",
   "translateTerm": false,
   "caseSensitive": true,
   "term": [
       {
           "lang": "en",
           "term": "Neil Mulholland"
       }
   ]
}

The translateTerm key is set to false because we do not want Localazy to translate this term. It is also a case-sensitive term because any other case of the term is not in a valid glossary and will be available for translation in Localazy.

The id of the newly created glossary is returned in the response.

We can go to the Localazy dashboard and navigate to the Glossary tab and expect to see something similar to this:

article-image

🖼️ Create a new screenshot using the API 🔗

The Localazy API allows you to create screenshots. The screenshots feature is available in the Autopilot plan and higher tiers. You can upgrade your account by navigating to your dashboard billings page.

We can upload a new screenshot for our project by sending a POST request to the URL https://api.localazy.com/projects/{projectId}/screenshots

Where projectId is the ID of the project.

The request object should be a base64-encoded image in data format. Images can be converted to a base64-encoded format here.

It is important to note:

  • Images in JPEG or PNG format are supported.
  • The image must be at least 36x36 pixels in size.
  • The image must be 4096x4096 or smaller in width.
  • The image must be less than 5 MB in size.

The response body contains the identifier for the newly created screenshot.

In your dashboard, navigate to the screenshot tab, and you can see the new image

article-image
There are many other options that allow for screenshot management entirely automated via the Localazy API. Read more in the Screenshots API documentation.

🎛️ Advanced Options Overview 🔗

Manage duplicate strings using API 🔗

Multiple files can be imported to Localazy with similar source keys. This can lead to source key duplication in the imported content. Luckily, you can use Localazy to resolve issues coming from duplicate content with the feature called Duplicity Linking.

Duplicity linking is available from the Agency plan.

In this section, we will look at how to use the Localazy API to resolve duplicate strings. If you have duplicate keys in your project, you can solve them by linking them together. When a key is linked to another, it copies its content when it is published.

When a key is linked, it is marked as hidden by default and does not need to be translated. It can have its own content, but it is not used during publishing and is replaced by the content of the linked key as long as the link is present.

Please keep in mind that existing links can prevent you from performing certain actions, such as deleting target keys or clearing project content.

It's not possible to create a link to a key that is already linked to another one.

To test out duplicates and manage duplicities in our project, we'll need to create duplicates of values, which we'll do by importing another file with a body request like this:

{
 "files": [
   {
     "name": "duplicated-translation.json",
     "content": {
       "type": "json",
       "en": {
           "title": {
               "title1": "The Psychology of Harry Potter",
           },
         
           "description": {
               "description1": "Harry Potter has provided a portal to the wizarding world for millions of readers, but an examination of Harry, his friends and his enemies will take us on yet another journey: through the psyche of the Muggle (and wizard!) mind.",
               "description2": "This is the gripping inside story of Ireland's bankrupt billionaire, Sean Quinn, who went from rags to riches before gambling it all on Anglo-Irish Bank shares and became the world's biggest personal loser of the economic collapse of 2008."
            
           }
       }
     }
   }
 ]
}

You'll notice that the content has values that are similar to those in the translated.json file that we imported into Localazy initially. Duplicities exist between:

  • title.title1 of the duplicated-translation.json and the title.title1 of the translation.json
  • description.description1 of the duplicated-translation.json and the description.description1 of the translation.json  
  • description.description2 of the duplicated-translation.json and the description.description2 of the translation.json  

You can see the percentage of duplicates in the Translations tab of your project or by navigating to the Developer Console.

article-image

You can click on "Resolve duplicities" to easily track the duplicities that will be resolved using the API. As shown below, we currently have three unresolved duplicates.

article-image

Send a POST request to the URL https://api.localazy.com/projects/{projectId}/links/{keyId} with the following request body:

{
"keyId": "_a7917183974514294216",
"project": "_a7922645342385287434"
}

The projectId in the URL parameter is the id of the source translation file's project (translation.json), and the keyId is the id of the key to be linked to (title.title1).

The keyId in the request object is the id of the target (title.title1), and project is the id of the target file (duplicated-translation.json).

article-image

A successful request returns a true value, and you should see the linked key in the resolved tab of the duplicities on your dashboard.

Learn more about Duplicity Linking feature on the Localazy Blog

Manage webhooks using API 🔗

Webhooks are user-defined custom callbacks on specific Localazy actions. There are currently five actions available to hook into your system.

These actions include:

  • comment_added - This hook is triggered when a comment is added to the project.
  • import_finished- This webhook is triggered when importing is finished. This happens only when there are added, updated or deprecated keys.
  • import_finished_empty- The webhook is invoked when importing is finished. This event is invoked when the importing is finished with no changes.
  • project_published- This is triggered when the project is successfully published.
  • tag_promoted- This webhook is triggered whenever a release tag is promoted to another tag.
The webhooks feature is available in the Autopilot plan and higher tiers.

Localazy authenticates the webhook events it sends to your endpoints by including a signature in the request header. This enables you to confirm that the events were sent by Localazy rather than a third party.

Now let's try creating a new webhook configuration, that gets triggered when a new comment is added to our project, via the Localazy API.

Navigate to Postman and send a POST request to the URL: https://api.localazy.com/projects/{projectId}/webhooks

The request body is similar to the following snippets:

{
 "items": [
   {
     "enabled": true,
     "customId": "custom-id",
     "description": "Inform backend when a comment is added.",
     "url": "https://webhook-target-url.com/webhook",
     "events": [
       "comment_added"
     ]
   }
 ]
}

The result is returned as a true value. And you can check the new webhook inside the Localazy platform by navigating to the project settings.

article-image

How does the API work with Localazy CDN? 🔗

Because Localazy API is not designed to serve translated content directly to your users, you should use the Localazy CDN instead. You can use the Localazy API to obtain CDN metadata and serve your end-users always up-to-date translations.

Localazy CDN is a reliable way how to deliver fresh translations across the globe with low latency. Build on top of Amazon technologies, your localizable files are available from numerous data centers all around the world. Localazy CDN is suitable for deployments in production. It delivers translated files quickly and reliably and can accommodate a large number of users from around the world.

We also make additional metadata available through the CDN allowing you to build automated localizable solutions controlled fully from within Localazy.

Learn more about Localazy CDN on the blog

✔️ Conclusion 🔗

And that's it! Now you are ready to manage many aspects of your Localazy projects programmatically. I hope you tried all examples above and hopefully discovered new possible ways to further automate your localization workflow using the Localazy API.