Localization (i18n) #

Factor supports localization or i18n (short for internationalization) via a simple lang file system that integrates with settings.

Let's go through the steps needed to:

  • Set your app's locale / language
  • Add custom translations
  • Contribute translations to core or plugins

Setting Your Locale #

The first step in changing your app's language is to set the "locale" which is a standard language based code. For example, English is en and Spanish is es, etc...

You can see a full reference of language codes at the bottom of this doc.

Note that the default and fallback language code is english en.

There are three ways to set the locale:

Using setLocale #

You can set the locale with a function setLocale in your main files. This has the advantage of being potentially dynamic, allowing you to change the language based on user preference.

// index (main file)
import { setLocale } from "@factor/api"

// Set to Spanish locale
setLocale("es")

Using Config #

You can also set the locale via package.json or FACTOR_LOCALE in .env. This is a more reliable way to set a permanent language for your app.

# .env - Set to Chinese
FACTOR_LOCALE="zh"

or in package.json:

{
  "factor": {
    "locale": "it" // Italian
  }
}

Custom Translations #

Now that your locale is set, you are set up to pull in translations and add custom ones of your own.

Factor translation works with factor-lang-[language-code].ts files. These are automatically compiled at build and loaded based on your locale. They are then merged with factor-settings.

So to add custom Spanish translations to your app, first identify the settings file that you'd like to translate. As an example, if a plugin has a file factor-lang-en.ts with the following object:

// factor-lang-en.ts
export default {
  thePlugin: { greeting: "hello!" },
}

You could add a factor-lang-es.ts file to your app with the following:

// factor-lang-es.ts
export default {
  thePlugin: { greeting: "hola!" },
}

Now if your locale is es whenever that plugin uses setting("thePlugin.greeting") it will pull in the localized es value:

import { setLocale, setting } from "@factor/api"

setLocale("es")

setting("thePlugin.greeting") // "hola!"

Adding Translations to Plugins, Themes or Core #

Since finding settings files and then adding custom translations can be a hassle, its much easier if translations already exist. However, this doesn't happen without contributions from users such as yourself

To add a custom translation, just fork any repo and add your lang file. Then, when your ready just create a pull request.

Most authors, including us, are happy to accept translations in your language!

Language Codes #

  • Afrikaans: af
  • Albanian: sq
  • Arabic: ar
  • Armenian: hy
  • Azerbaijani: az
  • Basque: eu
  • Belarusian: be
  • Bulgarian: bg
  • Catalan: ca
  • Chinese: zh
  • Croatian: hr
  • Czech: cs
  • Danish: da
  • Dutch: nl
  • English: en
  • Estonian keel: et
  • Filipino: tl
  • Finnish: fi
  • French: fr
  • Galician: gl
  • Georgian: ka
  • German: de
  • Greek: el
  • Haitian: ht
  • Hebrew: iw
  • Hindi: hi
  • Hungarian: hu
  • Icelandic: is
  • Indonesian: id
  • Irish: ga
  • Italian: it
  • Japanese: ja
  • Korean: ko
  • Latvian: lv
  • Lithuanian: lt
  • Macedonian: mk
  • Malay: ms
  • Maltese: mt
  • Norwegian: no
  • Persian: fa
  • Polish: pl
  • Portuguese: pt
  • Romanian: ro
  • Russian: ru
  • Serbian: sr
  • Slovak: sk
  • Slovenian: sl
  • Spanish: es
  • Swahili: sw
  • Swedish: sv
  • Thai: th
  • Turkish: tr
  • Ukrainian: uk
  • Urdu: ur
  • Vietnamese: vi
  • Welsh: cy
  • Yiddish: yi