The ultimate guide to Localazy CDN

When working on a software project, you usually master the programming language used for its development. You can "speak" it fluently. Even though it's normal to introduce bugs, you can avoid many of them by testing your code. Thanks to your knowledge, tools, and processes, you can ship a product that's great and comes with no critical errors.

All of this essential knowledge resides in your team. It, however, doesn't apply to localization, as most SMBs can't afford the luxury of having internal people speaking all the supported languages.

"Bugs" in localization are often not as critical as your software crashing completely, but they can still have adverse effects - it's not uncommon for people to lose their data because of a bad translation; they don't understand what they are doing because the translation provides misleading information. Such an issue can earn you bad reviews and potentially drive many users away from your product.

When a critical bug in the software is found, it's usually necessary to fix it, run all the tests to ensure everything works correctly with the updated code, prepare the release, and publish it. You don't want to do all of this just because there are a few issues in translation.

So, is there a better way?

You probably expect me to say: "Yes, it is." and you are right; there's indeed a better way with more benefits than just fixing issues… The answer is Localazy CDN.

💙 What are the benefits? 🔗

Several vital benefits make CDN a perfect part of the localization process. So, what can you do with CDN?

Fix localization fails. And do so without the need to release a new version of the app.
Speed up releases. When there is a mechanism to update translation over the air, you can get the new version of your app out quickly and finish less important languages after the release.
Add languages dynamically. Without downloading the new version of your app, the users can just start using it in their language when it's ready.
Remove developers from the localization process. No need to bother developers whenever there's a fix in translated files to be published. All the changes are live in a couple of minutes without any interaction. Developers will thank you since they won't waste their time on trivial tasks anymore. And business people, too - they can get their changes up and running quickly.

⚙️ Prepare your project 🔗

Whether you work on a web or mobile app or a good old desktop app, you need to prepare your project for localization and upload localizable files to Localazy. This process is out of the scope of this article, but there are tons of resources on this topic in our documentation and blog tailored for your specific technology, platform, and framework.

See the list of available integrations and supported file formats.

Once you have your localizable assets managed on Localazy and enable our CDN, we do a lot of work for you in the background automatically!

🗃️ Files on CDN 🔗

Whenever your data is changed, such as when you upload new texts or when there are new translations, we automatically create a new version of your files and upload it to CDN. There is no action required on your side.

Not only do we upload your translated files, but add them packed as a ZIP archive, which is very useful for constrained environments, as described below. And, on every change, we generate a new metafile.

We also automatically send invalidation requests to the CDN network to ensure that updated files are available as soon as possible. However, it may still take up to 15 minutes for changes to propagate to all servers.

🗂️ The metafile 🔗

Metafiles describe the current state of your data available on CDN, and they are described in detail in the documentation.

The metafile is specific per release (releases are described below), allowing you to rely on its content for fully dynamic functionality even with different releases. It's great since you can quickly implement mechanisms to support testing, staging, and production environments, even in the ever-changing world of translation.

There are a bunch of valuable details you can get from the metafile, such as the filename and path for each of the files and all languages for each of the files, including:

locale code
English and localized name
URL to CDN for each of the languages
timestamp of the last update
function for resolving plural form (in JS/TS file)

🚀 Releases 🔗

The speed of distribution - both in the sense of how fast you can get new translations out and what your end users' latency is - is one of the core advantages of CDN. However, you may still want to retain control over quality while ensuring that you can quickly send updates to your users. And that's what Releases are great for!

Learn more about Releases in the docs

Because Localazy CDN works smoothly with the Releases feature, you can link to different versions of your files and be sure that recent changes will not break your website/app.

In Localazy, all changes (newly added keys, updated ones, new translations, reviews, etc.) are automatically published as the latest tag. This is a good option to use during development when you don't care much about the content.

Using Releases gives you control over which translations are ready to go public by creating release tags. E.g., when you are happy with the current translation quality, you can promote the latest release tag to staging and make the progress available in your testing environment.

At this point, the translation is close to the final version, but - similarly to the software development - it's common that many localization issues will be identified. They can be quickly fixed in Localazy, reviewed in the development, and again promoted to the staging tag.

Once you are sure that the new version of your app is ready for its prime time, you can just promote the staging tag to either production or vX.X.X depending on your preferences. Using the versioned tag is a better option if you support more active versions in production.

If you find any critical issue in translations, you can still use release merging to propagate only a portion of changes from the latest or staging tag.

Also, you can omit the step with the staging tag entirely and use the latest one directly in a testing environment. Using staging is an excellent way to achieve reproducibility, which may be limited when translations change under testers' hands. It's, amongst other reasons, important for the translation context. Sometimes, the translators need to see where and when the translation is used to adapt it correctly.

One pro tip: It's possible to use merging to release only a subset of languages — more on this topic in the "Deliver languages dynamically" section.

💡 Implementation 🔗

Now that we have our releases/files available on CDN, it's time to implement the logic for your app. There are three types of apps with different behavior:

Always-online approach 🔗

The simplest way to use translations from CDN when your app is always online - such as your website or SaaS product - is to download the localized file directly from CDN every time.

There's an article on this topic on our blog that goes into more technical details with Javascript and the i18next library.

Not only it's the simplest way to integrate CDN, but it's also how CDN was designed to work in the first place, and it brings many benefits:

You don't need to care about the infrastructure: no need to store files, solve distribution, backups, fallback servers, HTTPS, invalidation, etc. It just works! We take care of it.
Your files are delivered from servers closest to your customers, lowering response time considerably. Have you ever tried to download files from servers in the US while being in Japan? Being close to your customers (in terms of latency) is an integral part of localization and customer experience. We are not talking about an image that lags and loads slowly. We are talking about texts and translations that are an essential part of the app.
Our CDN is not just delivering files: it also provides helpful metafiles and transparently supports releases. In a sense, you can control your app's localization using our CDN - e.g., you can add languages dynamically without bothering developers.

Offline approach 🔗

When your app can be used offline, you must make the translations available even without an internet connection. The best approach is to bundle the current translations when building a new version of your app, and making Localazy CLI part of your CI/CD is a perfect way to do it automatically. This way, you can be sure that the app has the latest translations even when started offline for the first time.

Whenever an internet connection is available, you download files from CDN to ensure that the latest translations are included, and you also update stored translations so that next time, when the internet connection is unavailable, your app resorts to the latest version.

This combines the best of both worlds - keeping the app updated with the latest translations while maintaining offline availability.

Constrained environments 🔗

There is also a special variant of apps that are typically online but that are required to have very low data transfers. This can apply to mobile apps where content changes are rare and keeping them updated is unimportant or for apps designed for specific use cases. We worked on such an app years ago - it was designed for a rural environment with an unstable and slow connection.

In such situations, you can leverage our metafile and periodically check for timestamp on the global or even file level to detect changes. If timestamp is not equal to your stored version from the last check, update translations and you'll possibly get new languages! By the way, the timestamp property is not a UTC-based timestamp but the internal ID of the last change that is guaranteed to be higher for subsequent changes.

Depending on how many files were changed, you can download just the changed files or redownload all of them in ZIP format, further reducing the download size with the compression.

🌟 Update your marketing message 🔗

With CDN, you can update your texts online. It's a fantastic way to fine-tune your marketing message, adapt banners, or improve the performance of calls to action.

We even saw CDN being used for customized banner colors since, in different languages (and cultures), colors can have quite different meanings!

A/B Testing with branches

You can use our Branching feature to create a branch of your project. The branch is a copy of the project, so you start with identical content, and you can change specific texts and translations.

In your product, you can randomly select a URL to obtain the metadata file. From the metadata file, you get links to all the localized assets, so apart from a list of URLs, you can get everything else from our CDN directly.

This way, you can easily switch between different variants of your texts and translations. Send the CDN URL to analytics, and you'll be able to measure which variant performs better!

🧭 Deliver languages dynamically 🔗

We've already mentioned the option of adding languages to your app dynamically. With the metafile, it's pretty easy. You can download the metafile first and review all the contained files. Each file comes with a list of languages it's available in. You can collect all the languages by just traversing the files, and you can even include only languages in which important files are available.

For each language, you get additional information, such as English and localized names, whether it's RTL or LTR, plural formula (described below), etc. You can use them to render a beautiful language selector dynamically without storing any information hardcoded in your app. And, of course, you can also automatically preselect a language based on user preferences or based on language autodetection.

There's also the baseLocale property in the metafile, so you can automatically fall back to your project's source language if the user has no preferences stored and autodetection fails.

And you can control all of this right from Localazy. It's not just a translation management system to translate texts: it can act as a control center for your app's localization.

However, the logic described above is straightforward. Still, it would add any language defined on Localazy to your app, which may be undesirable behavior for languages that don't yet meet your quality criteria or those that are not yet fully translated (or translated to some minimal extent).

Luckily, two options allow you to solve that…

Localazy as a control center 🔗

In Localazy, you can control what languages are exported. This option is known as enabled/disabled languages.

What's incredible is that disabled languages will still be available to translators, so you can keep improving them without exposing them to public audiences. Once they're ready to be used, you can just re-enable them, and they will be published and available to your app's users without any changes to the app's code.

This way, you can control available languages comfortably directly from Localazy. It's a perfect method for non-technical users, but it has a minor drawback. Since the setting is global, you can't easily have different sets of languages available in the development, staging, and production environments. If you don't release often, you can disable the languages before publishing the latest and promoting it to the staging/production phase. However, it's error-prone and needs an extra process.

If you don't need to have untranslated languages on testing/staging, it's the way to go. Built-in to Localazy and very comfortable with our UI.

Releases with limited languages 🔗

Suppose you need different sets of languages available in development, staging, and production - for example, when some languages are not yet fully translated or the quality is not yet perfect, but you already need them available for testers -. In that case, you can use merging instead of promoting releases through Localazy CLI.

The simple command below will merge the latest tag with itself (which effectively means processing it as is) but remove all the languages that are not listed in --languages. The result is stored as the staging tag.

localazy merge --languages en,cs,de,fr,es --remove-unlisted-languages latest latest staging

You can use the same approach to create the production tag if you need to limit the available languages further, or you can just promote staging to production (or versioned tags as described in Releases) when required.

🤓 Plurals 🔗

The metafile in JavaScript and TypeScript versions has functions for resolving plural forms. For example, for the Czech language, the definition would be:

"plural": (n) => { return (n===1) ? "one" : (n>=2 && n<=4) ? "few" : "other"; }

It accepts a number and returns the corresponding plural form based on the CLDR definition for integer numbers.

Plural functions help you with implementing fully dynamic localization controlled from Localazy. You don't need to learn the logic behind and hard-code the definition into your app; you would need to update it whenever you want to add a new language. When using the function directly from Localazy, you just add the language and get the function out of the box.

However, it's worth noting that since it's based on the CLDR definition, it may not be available for all languages (currently, it's 80+ most common languages). Hence, a reasonable default is an excellent way to go.

🤔 Limitations & Solutions 🔗

Format conversions are unavailable, but there is a solution!

One of the most significant limitations of CDN is that files must be generated and placed on the storage from which they are available for worldwide distribution before the requests from your users start coming in. It's necessary to achieve the extremely low latency we strive for. Unfortunately, this disallows dynamic features, such as format conversions, beloved by CLI users.

This limitation is very rare, as a unified format is usually used to deliver translations even across multiple platforms.

If you still need to deliver the same file in multiple formats over CDN, this can be easily achieved with our export aliases. Just export the desired keys to another file with a different format and voilá: you'll get that file on CDN as well!

Cache invalidation and dev environment

Another slight limitation is that, even with the invalidation requests we send to CDN, the changes may not be reflected immediately, and it typically takes up to 15 minutes before the updated files are available for download. It's not a production problem, but it may be a bit of a pain during development when you need to test rapid changes or on the CI/CD pipeline.

The recommended workaround is to serve the files from your local drive using a simple HTTP server to simulate the CDN. With one-liners such as Python 3's HTTP server (python -m http.server), it's actually a matter of minutes to write a script that copies the files to the correct structure and starts the server to simulate production CDN.

✔️ Conclusion 🔗

I hope you got inspired to try the Localazy CDN now that you have learned about its possible applications. Maybe you have even developed some niche use cases on your own? Share your setup in the comments to inspire others!