Localization and Internationalization (i18n) Guide

Welcome to the Finch Localization and Internationalization (i18n) Guide! This guide will walk you through the steps to localize and internationalize your Finch application. Whether you're a seasoned developer or just starting, Finch offers a robust set of tools to simplify server-side web app development.

i18n in Finch

Finch provides a built-in i18n system for localizing and internationalizing your application. The i18n system allows you to define multiple languages and translate your application's text into those languages.

How to use i18n in Finch?

Localization in finch can be done in two ways, you can use Json files or define languages in the languages.dart file.

1. Using Json files

in Finch, you can use JSON files to define your languages. By default, Finch looks for language files in the lib/languages directory. You can create a new JSON file for each language you want to support. For example, you can create a fa.json file for Persian language.

It is very simple to use i18n in Finch. You just need to define your languages in the en.json or other language file. Here is an example of how to define languages in the fa.json file:

{
  "dir": "rtl",
  "example.params": "نام من {name} است، سن من {age} سال است",
  "example.path": "مسیر تست از example.path برای محلی‌سازی",
  "example.tstring": "تست اشیاء TString برای i18n",
  "logo": "Finch",
  "logo.title": "Finch"
}

2. Using `languages.dart` file

You can also define your languages in the languages.dart file. Here is an example of how to define languages in the languages.dart file:

var languages = <String, Map<String, String>>{
  'fa': {
    'dir': 'rtl',
    'example.params': 'نام من {name} است، سن من {age} سال است',
    'example.path': 'مسیر تست از example.path برای محلی‌سازی',
  },
  'en': {
    'dir': 'ltr',
    'example.params': 'My name is {name}, I am {age} years old',
    'example.path': 'Test path from example.path for localization',
  },
};

After defining your languages, you need to configure Finch to use dart files for i18n. You can do this by setting the dartLanguages property in the FinchConfigs object. Here is an example of how to configure Finch to use dart files for i18n:

FinchConfigs configs = FinchConfigs(
  // only for json files
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? "./lib/languages"), 
  // set language source to dart or json
  languageSource: LanguageSource.dart,
  // the map of languages defined in languages.dart file
  dartLanguages: languages,
);

LanguageSource.dart and LanguageSource.json are two options for the languageSource property. You can choose either one based on your preference. then, pass the configs object to the FinchApp constructor:

FinchApp app = FinchApp(configs: configs);

i18n in templates

You can use i18n in your templates by using the {{ $t('logo.title') }} syntax. For example, if you want to translate the logo.title key, you can do it like this:

<h1>{{ $t('logo.title') }}</h1>

i18n in controllers

it is very simple to use i18n in your controllers. You can use the "string".tr method to translate your text. For example, if you want to translate the logo.title key, you can do it like this:

rq.renderString(text: 'logo.title'.tr);

parameters in i18n

You can use parameters in your i18n text. For example, if you want to translate the example.params key, you can do it like this:

rq.renderString(text: 'example.params'.tr.write({'name': 'Alexandre', 'age': 30}));

and in your template you can use it like this:

<p>{{ $t('example.params', {'name': 'Alexandre', 'age': 30}) }}</p>

array parameters in i18n

You can use array parameters in your i18n text. For example, if you want to translate the example.params key, you can do it like this:

rq.renderString(text: 'example.params'.tr.writeArr(['Alexandre', 30]));

and in your template you can use it like this:

{
    "example.params": "نام من {0} است، سن من {1} سال است",
}

<p>{{ $t('example.params', ['Alexandre', 30]) }}</p>

On This Page