Localization (i18n)

Localization, or internationalization (i18n)

Localization (i18n) in WebApp Package

Home documentation

Localization, or internationalization (i18n), is the process of adapting your web application to support multiple languages and regions. This guide explains how to set up localization in the WebApp package, including configuring language files and using translation functions in Dart code.

Setting Up Localization

1. Configuration

To enable localization in your WebApp application, you need to configure the path to your language files in the WaConfigs setup. The configuration specifies where your language files are stored and other relevant settings.

Here is an example configuration:

WaConfigs configs = WaConfigs(
  widgetsPath: pathTo("./example/widgets"),
  widgetsType: 'j2.html',
  languagePath: pathTo('./example/languages'),
  port: 8085,
  dbConfig: WaDBConfig(enable: false),
  publicDir: pathTo('./example/public'),
);
  • languagePath: Specifies the directory where your language files are located (e.g., ./example/languages).

2. Creating Language Files

Language files should be placed in the directory specified by languagePath. Each file should be named according to the language code (e.g., en.json for English, fa.json for Persian).

English Language File (en.json):

{
  "dir": "ltr",
  "example.params": "My name is {name}, my age is {age}",
  "example.path": "Test path of example.path for localization",
  "example.tstring": "Test TString objects for i18n",
  "logo": "WebApp",
  "logo.title": "WebApp",
  "pages.title": "Title"
}

Persian Language File (fa.json):

{
  "dir": "rtl",
  "example.params": "نام من {name} است، سن من {age} است",
  "example.path": "تست مسیر example.path برای محلی سازی",
  "example.tstring": "آزمون رشته‌های تی TString برای بین‌المللی سازی",
  "logo": "وب اپ",
  "logo.title": "وب اپ",
  "pages.title": "عنوان"
}
  • dir: Specifies the text direction (e.g., ltr for left-to-right, rtl for right-to-left).
  • Translation Keys: Define the translation keys and their corresponding values for different languages.

3. Using Translations in Widgets

In your templates or widgets, you can use the $t function to get the translated text. The function looks up the translation key and returns the appropriate text based on the current language.

Example usage in a widget:

<a class="navbar-brand ms-2 text-white" href="/"><?= $t('logo.title') ?> <?= version ?></a>
  • $t Function: Retrieves the translated text for the given key.

4. Using Translations in Dart Code

In Dart code, you can use TString and .tr methods to handle translations. This approach allows you to work with translation strings programmatically.

Example Dart code for localization:

Future<String> exampleLanguage() async {
    rq.addParams({
      'exampleTString': TString('example.tstring').write(rq),
      'examplePathString': 'example.path'.tr.write(rq),
      'exampleTranslateParams': 'example.params'.tr.write(rq, {
        'name': 'Alexandre',
        'age': Random().nextInt(100),
      }),
    });
    return renderTemplate('example/i18n');
}
  • TString: Represents a translation string object that can be used to fetch and format translations.
  • .tr Method: Retrieves the translation for the given key and allows for parameter replacement.

Summary

Localization in the WebApp package involves setting up language configurations, creating JSON files for each language, and using translation functions in both templates and Dart code. By following the setup process and using the provided examples, you can easily adapt your application to support multiple languages and enhance the user experience for a global audience.