Skip to main content

​
Quetzal’s Role

Quetzal is designed to work with whichever systems and libraries you are already using. We do not provide libraries or tools to be installed in your code. Instead, you first decide on a localization scheme on your end, and Quetzal can take charge of managing it. This lets you have all of the freedom to implement localization in a way that works for you, but with the confidence that the legwork to maintain it will always be completed. However, we have some tips in picking the best framework, if you do not yet have one

​
Scope

As a reminder, these tools and tips are designed for translating static strings defined within your codebase. If you have other content in need of translating, you can use our API.

​
The Worst Thing You Could Possibly Do

The single worst possible choice for code localization is to try to roll your own, or localize without relying on an existing system. We see countless codebases with entirely novel and custom translation mechanisms, and they very often have blind spots which force heinous patterns for translating strings down the line. It is strongly recommended to use a battletested solution, even if it seems like overkill at the start.

​
Rule of Thumb

Most of the time, there will be several localization patterns for your stack. We recommend:
  • First Party Any time there is a localization scheme baked into the stack (ie, Apple’s Swift localization, Android’s string resource loading, packages like @angular/localize) it’s usually a sign that it is maintained specifically for your use case. Unless you have a good reason, opt for this first.
If no first party scheme exists, you should look for something:
  • Open Source: If no good first party solution exists, you are looking for the most beloved third-party open source solution. There is usually only a couple.

​
Variation Between Localization Mechanisms

There are a few ways in which localization patterns differ, and while all have their place, here are some thoughts on the differences you will encounter in practice:

​
Key vs. Exact Text

Most localization systems rely on keys to map to text. So the text “Hello!” might map to “greeting.standard”, and your code will refer to “greeting.standard” as the primary unit being translated. Some codebases will try to avoid this, and instead use the raw text as the unit of translation. This can make code more readable, and reduces cognitive load (you don’t need to keep track of another data point, a key) However, we highly recommend you use keys, even if your solution supports a plaintext approach. There are two reasons: 1- Complex strings can run into formatting issues 2- Disambiguating the translation content from the translation id makes updates more graceful If code readability is a concern, often you can include the plaintext version as a placeholder at the moment of translation. Many libraries offer support for both patterns, so it is crucial to think through which you want to use before handing your code off to Quetzal.

​
Extraction vs. Manual Updates

Some systems rely on developers manually seeding translation files. Other systems have a script which parses your code, and builds translation files automatically. Other systems allow for both. Both systems have their place and work just fine. Extraction based systems are stricter about code structure, but require less upkeep. Since Quetzal will manage your translation files regardless, we would suggest you go with a system that relies on manual updates. This gives us an easier time updating the files ourselves. In some cases, extraction based systems also demand more cognitive load to ensure compliance, which comes with limited benefit when using Quetzal.

​
String formatting

For complex strings with plurals or other dynamic values, your library will often have their own rules and patterns for encoding strings. At Quetzal, we love the ICU Message Format which is the best attempt at standardizing these rules. While we support all formatting schemes, make sure the format is flexible enough to handle the structure and variance you will need.