What is Localazy Translation API

Localazy started with CLI as the primary tool for uploading content and downloading translations between Localazy and one's project. It is the most powerful and versatile approach, but there are specific scenarios where only CLI might not be the most suitable option for the localization of parts of your project.

💡 Why even use API

Imagine, for example, that you're running a small 🛒 e-commerce website. In such instance, it is often crucial to be able to fix typos and product descriptions instantaneously to keep everything up to date and provide visitors with the best shopping experience possible. Doing a release just because of textual changes might not be a viable approach. And that's where API shines.✨

Users can use Localazy API for fetching up-to-date content as well as for its modification. That sounds very unspecific, though. So let's list some specific examples and how it differs from the static-content-based approach.

Show website visitors the latest translations in all available languages. With static files only, you'd show them translations in languages that were available during the last release (which could be a couple of weeks old).
Greet all users of your mobile app with a frequently changing welcome message. They will see the latest message as long as they are connected to the internet, regardless of whether they have downloaded the latest version of your app; if not, it fallbacks to the static content. With the static approach only, they will see a message defined during the last app version release, i.e., the message depends on whether users update your app.
Build an internal web-based portal for your company employees so that they can use only your system without the need to sign into Localazy. You could run the CLI on the backend and build your own API for the communication, but API allows for a client-side solution that will be quicker to implement.
Create a public community plugin on NPM. Unless you're building a plugin for projects based on Node.js only, API is pretty much the only viable option.

As you can see, there are scenarios where API just makes sense. Of course, the list isn't exhaustive, and there are countless scenarios and cases where using Localazy API is the way to go.

📖 Learn more about Localazy API in the documentation.

🤔 How about Localazy CDN?

Localazy CDN is a fast and reliable way to retrieve translated files directly from Localazy. As such, you can use it similarly to API's files endpoints. However, there are some differences.

The biggest one is that it can be used for reading the translations only - you cannot use CDN to modify the content in Localazy. The other important difference is that API comes with certain request limitations. You can send only a maximum of 100 requests per minute and 10 requests per second. Additionally, usage of API is free of charge while CDN isn't, though it costs very little (less than 1 cent per 1000 requests).

Furthermore, API accesses the data directly from servers. In contrast, CDN translations reside in files that must be generated (just as the CLI download command creates files) and then stored on the CDN provider's servers. So instead of fetching the data directly, you're actually fetching the latest published files. It generally takes a little more time for the changes to propagate to CDN, while API always returns the up-to-date translations.

📖 Learn more about Localazy CDN in the documentation.

All in all, if you either need the latest translations or you want to modify some content in Localazy, you should opt for API. If you prefer fast and globally available translation files to utilize all the benefits of content delivery networks, go with it.

However, there are two scenarios where using both API and CDN is recommended. Firstly, CDN resources are accompanied by metafiles that provide information about project languages such as plural forms, whether it's right-to-left language or what is its localized name. Such information allows you to build language selectors dynamically and adjust website layout appropriately. Secondly, for frequently visited websites the maximum number of requests per minute and second could be limiting. In that case, it is advisable to use CDN for the production version and a combination of API and CDN for the development environment in order to fetch the latest data during development without having to wait for CDN content to be updated.

▶️ How to get started

The best place to start is by reading the documentation. To sum it up, you need to 1. Sign up at Localazy. 2. Create a project in Localazy. 3. Generate a project token for authentication/authorization.

If you use TypeScript or JavaScript in your project, you can also use our TypeScript library that makes operating with the API much more straightforward.

Ready to get started?

I hope this brief introduction provides you with a good understanding of what Localazy API is about and when to use it. Should you have any questions, don't hesitate to contact us via team@localazy.com, leave a comment below or join our Discord. Happy coding!