Localization in Apostrophe
For Apostrophe, "localization," often abbreviated as l10n, is the process of adapting the Apostrophe user interface and Apostrophe website content for different "locales," or groups of people (usually based on language and country). This can include text translation, date formats, content variation, and much more.
Localizing Apostrophe websites is done in two contexts:
- Static content: localizing "hard-coded" text and other information. This primarily involves strings in template files and the Apostrophe user interface components. This will usually involve a developer, though translation will likely be done by other people. See the related guide for more on this.
- Dynamic content: translating and generally customizing content controlled through the user interface. Depending on the website needs, this may mean direct translation between locales, but may also mean major content changes for the different groups of people. This work is usually done by content editors and translators. See the related guide for more on this.
What about "internationalization"?
The term "internationalization," often abbreviated i18n comes up when discussing this as well. And for good reason. See the localization section of the glossary for a quick overview of how we use these terms. Put simply, we use "internationalization" to refer to the system that supports the localization processes. That's why the core Apostrophe module is
The first step in localizing content, whether static or dynamic, is to define locales. These are most often different languages, countries, or combinations of the two. In some cases it may also be appropriate to establish locales for people based on topical interests, professional categories, or cultural identities.
We configure locales through the
@apostrophecms/i18n module. In a project codebase, we can add a
modules/@apostrophecms/i18n/index.js file. The locales will go in its
locales option object.
Each locale needs a short identifier, which is typically a two-letter country code, language code, or one of each with a dash separating them. This will be the object key for each locale. For example, if we had a USA-based business working across North America we might have locales for US/general English speakers (
en) and Spanish speakers (
es), residents of Mexico using Spanish (
es-MX), Canadian French speakers (
fr-CA), and Canadian English speakers (
label property is used in the user interface.
- Locale names (e.g.,
'fr-CA') must begin with an alphabetic (non-numeric) character.
- The best practice for locale names is to use a two-character language code (
'en') or the language code with two character country code, capitalized (
'en-GB'). This will improve compatibility with i18n features as they are added to Apostrophe.
Additionally, we need to tell Apostrophe how to identify which one to use. This is done based on the URL used to access the website, either by the URL hostname, the URL path prefix, or a combination of the two.
hostname is used for any locale:
baseUrlmust be set on the application, defining the default hostname, OR
hostnamesetting must be used on all locales
For this example, we'll assume we have
baseUrl: 'example.com' set on the application.
So how does Apostrophe choose the best locale to use? In many cases it is clear. If there is conflict, however, the best locale uses the following prioritization:
- The locale has both
prefixsettings and the URL matches both settings.
- The URL matches the locale's configured
hostnameand the locale has no
- The URL matches the locale's configured
prefixand the locale has no
- The locale is the default locale (when no other locale matches).
The default locale
The default locale is the locale used when no others match the URL better. It is typically the locale used by your website's primary audience. If no locales are configured, Apostrophe will use
en as the default locale name.
The default locale can be changed in one of the following ways:
- Configuring locales! The first one configured will be the default.
- Using the
defaultLocaleoption on the
@apostrophecms/i18nmodule to name another locale
The best practice when configuring locales is to explicitly set the
defaultLocale option if it should not be
It is important to configure locales, especially the default locale, before content entry begins. This is especially the case if your locales will not include
en. If content entry begins on the default
en locale and we later configure locales that do not include
en, that original content will disappear (until the
en locale is restored).