# Localization

Using `strings.xml` files, we store strings in different languages. We use Lokalise to manage our
translations, automated with GitHub Actions and Lokalise integrations and automations.

## Overview

All strings are stored in `strings.xml` files. In the UI layer, we use the `stringResource` function
to get the string from the `strings.xml` file and render them accordingly. These resources are
stored in the `common-res` module, and exported in whichever module needs them (this is probably
usually only the `app` module and the `common-ui` module).

Example:

`common-res/src/main/res/values/strings.xml`

```xml

<string name="add_to_playlist">Add to Playlist</string>
```

`common-res/src/main/res/values-ja/strings.xml`

```xml

<string name="add_to_playlist">プレイリストに追加</string>
```

```kotlin
import com.suno.android.common_res.R as CommonResR

val text =
    stringResource(CommonResR.string.add_to_playlist) // renders according to user device's language/locale
```

`strings.xml` files in different languages are stored in `common-res/src/main/res/values-<language>`
folders. We currently support these languages:

- English (en)
- German (de)
- Spanish (es)
- French (fr)
- Hindi (hi)
- Indonesian (id, in)
- Japanese (ja)
- Korean (ko)
- Brazilian Portuguese (pt-rBR)
- Portuguese (pt-rPT)
- Russian (ru)

## Automated Localization Workflow

![Lokalise workflow](/docs/localization/lokalise_workflow.png?raw=true)

Our localization process now follows this automated workflow:

1. **English text updates**: The English `strings.xml` file should be the only one manually updated
   by developers while developing features. This is the source of truth for all translations.
2. **Lokalise import**: When there is a push to the main branch (via a PR merge), Lokalise
   automatically pulls the English `strings.xml` file and imports any new strings into the project.
3. **Automated Translation**: Lokalise then automatically translates the new strings into all target
   languages through its automation system.
4. **Lokalise string file management**: All strings in all languages are available for download at any time via Lokalise.
5. **Nightly Synchronization**: Every night at midnight ET, a GitHub Action runs that:

- Pulls all the latest translations from Lokalise
- Identifies any differences between the current translations and the new ones
- If changes are found, raises a pull request with the updated translation files

6. **Manual Review + Merge**: The pull request must be manually reviewed by a team member before being
   merged into the main branch.

## Adding a new string

With the automated workflow, adding a new string is simple:

1. Add the string resource in English to `common-res/src/main/res/values/strings.xml.` while
   developing your feature.
2. Push your changes to the main branch via the feature PR.
3. The automated workflow will handle importing the string to Lokalise, translating it, and creating
   a PR with all translations.
4. Review and merge the PR when it's created (typically at midnight ET, or the
   action 'Daily Lokalise Pull' can be manually triggered).

## Plurals

Plurals are also supported in `strings.xml` files for referring to a quantity of nouns (i.e. "1
song" vs "2 songs"). The nomenclature for the key is the `VARIABLES` word to distinguish it from
regular string keys. (e.g. `songsVARIABLE`, `creditsVARIABLE`, etc.)

```xml

<plurals name="songsVARIABLE">
    <item quantity="one">1 song</item>
    <item quantity="other">%s songs</item>
</plurals>
```

```kotlin
val songsAmount = pluralStringResource(
    CommonResR.plurals.songsVARIABLE, // id
    songAmount.toInt(), // count
    songAmount.toInt() // formatArgs
)
```