> ## Documentation Index
> Fetch the complete documentation index at: https://quetzal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Choosing a Framework

> Advice for picking a reliable localization pattern for your codebase

## Quetzal's Role

Quetzal is designed to work with whichever systems and libraries you are already using.

This means that we do NOT offer libraries or localization tools to be installed into 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 are designed for 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.

Reinventing the wheel comes at great cost. Sooner or later you will realize that the wheel had hidden wisdom that you failed to capture.

At that point, ripping your homebrewed system out and starting fresh can be tricky (and, worst of all, Quetzal does not yet support this!)

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.

The up front ease is a trap- yes, installing a library for the first time can sometimes cause friction, but the payoff is worth it. Rely on an existing system at all costs

## Rule of Thumb

Most of the time, there will be several localization patterns for your stack.

Right off the bat, here are the ones you should look for:

* 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.

* 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.

### 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 requires manual updates. This gives us an easier time updating the files ourselves.

But outside of Quetzal, both systems work fine.

### 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](https://unicode-org.github.io/icu/userguide/format_parse/messages/) which is the best attempt at standardizing these rules.

If your framework uses this, consider yourself lucky.

If your framework uses some other insane formatting logic, consider yourself lucky you can offload the struggle onto us.