# Localization

<div id="introduction"></div>
## 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.

<br>

#### Example of a localized file: `lang/en.json`
``` json
{
  "documentation": "documentation",
  "changelog": "changelog"
}
```
#### Example widget
``` dart
...
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`
``` json
{
  "documentation": "documentation",
  "changelog": "changelog"
}
```
#### Example of a Spanish localized file: `lang/es.json`
``` json
{
  "documentation": "documentación",
  "changelog": "registro de cambios"
}
```

<div id="adding-localised-files"></div>
## 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`
``` dart
{
  "documentation": "documentation",
  "changelog": "changelog",
  "intros": {
    "hello": "hello {{first_name}}",
  }
}
```

#### Example: `lang/es.json`
``` dart
{
  "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.


<div id="localizing-text"></div>

## Localizing text

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

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

```

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

#### Example: `lang/en.json`
``` json
{
  "changelog": "changelog",
  "intros": {
    "hello": "hello"
  }
}
```

#### Example: `lang/es.json`
``` json
{
  "changelog": "registro de cambios",
  "intros": {
    "hello": "hola"    
  }
}
```
#### Example using nested json keys
``` dart 
"intros.hello".tr()
// or
trans("intros.hello");

```

<div id="arguments"></div>

### 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`
``` json
{
  "changelog": "changelog",
  "intros": {
    "hello_name": "hello {{first_name}}",
  }
}
```

#### Example: `lang/es.json`
``` json
{
  "changelog": "registro de cambios",
  "intros": {
    "hello_name": "hola {{first_name}}"
  }
}
```

#### Example to fill arguments in your json file.
``` dart 
// 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

```

<div id="updating-the-locale"></div>

## Updating the locale

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

``` dart
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. 


<div id="setting-a-default-locale"></div>

## 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.

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