Localization

• Introduction
• Adding localised files
• Basics
  • Localizing text
    • Arguments
    • Updating the locale
  • Setting a default locale

Introduction

Localizing our projects provides us with an easy way to change the language or experience for users in different countries.

If your apps primary Locale was en (English) and you wanted to also provide users in Spain with a Spanish version, localising the app would be your best option.

Here's an example to localize text in your app using Nylo.

Example of a localized file: lang/en.json

{
  "documentation": "documentation",
  "changelog": "changelog"
}

Example widget

...
ListView(
  children: [
    Text(
      "documentation".tr()
    ),
    // ... or
    Text(
      trans("documentation")
    )
  ]
)

This will display the text from the en.json file. If you support more than one locale, add another file like es.json and copy the same keys but change the values to match the locale. Here's an example.

Example of a English localized file: lang/en.json

{
  "documentation": "documentation",
  "changelog": "changelog"
}

Example of a Spanish localized file: lang/es.json

{
  "documentation": "documentación",
  "changelog": "registro de cambios"
}

Adding Localized files

We include a lang directory in the project that can be found at the root of the project. Inside here, you'll be able to include .json files for each locale. E.g. es.json for Spanish or pt.json for Portuguese.

Example: lang/en.json

{
  "documentation": "documentation",
  "changelog": "changelog",
  "intros": {
    "hello": "hello {{first_name}}",
  }
}

Example: lang/es.json

{
  "documentation": "documentación",
  "changelog": "registro de cambios",
  "intros": {
    "hello": "hola {{first_name}}",
  }
}

Once you’ve added the .json files, you’ll then need to include them within your pubspec.yaml file.

Go to your pubspec.yaml file and then at the assets section, add the new files.

You can include as many locale files here but make sure you also include them within your pubspec.yaml assets.

Localizing text

You can localize any text with a key from your lang .json file.

"documentation".tr()
// or
trans("documentation");

You can also use nested keys in the json file. Here's an example below.

Example: lang/en.json

{
  "changelog": "changelog",
  "intros": {
    "hello": "hello"
  }
}

Example: lang/es.json

{
  "changelog": "registro de cambios",
  "intros": {
    "hello": "hola"    
  }
}

Example using nested json keys

"intros.hello".tr()
// or
trans("intros.hello");

Arguments

You can supply arguments to fill in values for your keys. In the below example, we have a key named "intros.hello_name", it has one fillable value named "first_name". To fill in "first_name", we can handle it by passing in a value to the method below.

Example: lang/en.json

{
  "changelog": "changelog",
  "intros": {
    "hello_name": "hello {{first_name}}",
  }
}

Example: lang/es.json

{
  "changelog": "registro de cambios",
  "intros": {
    "hello_name": "hola {{first_name}}"
  }
}

Example to fill arguments in your json file.

// e.g. Locale('en') English
// ...
"intros.hello_name".tr(arguments: {"first_name": "Anthony"}) // Hello Anthony
// or
trans("intros.hello_name", arguments: {"first_name": "Anthony"}); // Hello Anthony

Updating the locale

Updating the locale in the app is simple in Nylo, you can use the below method in your widget.

String language = 'es'; // country code must match your json file e.g. pt.json would be 'pt

await NyLocalization.instance.setLanguage(context, language: language); // Switches language

What this will do is update the locale to (Spanish which is) es.

This can be extremely useful if you wanted to provide users with an options menu to select a language to use in the app. E.g. if they navigated to a settings screen with language flags and selected Spanish.

Setting a default locale

You may want to update the default locale when users open your app for the first time, follow the steps below to see how.

1. First, open the .env file.
2. Next update the DEFAULT_LOCALE property to your Locale like the below example.

DEFAULT_LOCALE="es" // e.g. for Spanish and you'll then need to add your new .json file in /lang/es.json