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 for users in different countries.

If your apps primary Locale was en (English) but you also wanted to 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")
    )
  ]
)

The above will display the text from the lang/en.json file. If you support more than one locale, add another file like lang/es.json and copy the 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

Add all your localization files to the lang/ directory. Inside here, you'll be able to include your different locales. 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 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 this value, pass 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.

"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

This will update the locale to Spanish.

If you widget extends the NyState class, you can set the locale by calling the changeLanguage helper.

Example below.

class _MyHomePageState extends NyState<MyHomePage> {
...
  InkWell(
    child: Text("Switch to Spanish"), 
    onTap: () async {
      await changeLanguage('es');
    },
  )

This is useful if you need to provide users with a 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