Skip to content

7. Internacionalização

7.1. Exemplo 21: Um aplicativo bilíngue

[Flutter] usa arquivos ARB ou o arquivo JSON do pacote [easy_localization]. [Android] tem um método próprio, integrado ao sistema: os textos do aplicativo são RECURSOS. O arquivo [res/values/strings.xml] contém os textos do idioma padrão, neste caso o inglês; cada tradução é um arquivo com o mesmo nome, em uma pasta cujo sufixo é o código do idioma. A tradução para o francês, [res/values-fr/strings.xml]:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/values-fr/strings.xml - os textos do aplicativo, em FRANCÊS
     (a tradução). O idioma padrão, o inglês, está em
     res/values/strings.xml: o Android escolhe o arquivo de acordo com o
     idioma do aplicativo (cf. exemplo 21).
     ===================================================================== -->
<resources>
    <string name="app_name">Exemples Kotlin</string>

    <!-- exemplo 21 -->
    <string name="ex21_title">Exemple 21 - deux langues</string>
    <!-- %1$s: o primeiro parâmetro, uma string -->
    <string name="ex21_hello">Bonjour %1$s !</string>
    <string name="ex21_today">Nous sommes le %1$s.</string>
    <string name="ex21_price">Une consultation coûte %1$s.</string>
    <string name="ex21_no_appointment">aucun rendez-vous</string>
    <!-- um texto plural: uma forma por "categoria" do idioma;
         %1$d: o primeiro parâmetro, um inteiro -->
    <plurals name="ex21_appointments">
        <item quantity="one">un rendez-vous</item>
        <item quantity="many">%1$d rendez-vous</item>
        <item quantity="other">%1$d rendez-vous</item>
    </plurals>
    <string name="ex21_add">Ajouter un rendez-vous</string>
    <string name="ex21_remove">En retirer un</string>
    <string name="ex21_calendar">Ouvrir le calendrier</string>
    <string name="ex21_server_title">Traduire une réponse du serveur</string>
    <string name="ex21_server_explanation">Le serveur RdvMedecins ne renvoie que des clés. C\'est le client qui les traduit :</string>
    <string name="errors_login_taken">Ce login est déjà utilisé par un autre compte.</string>
    <string name="errors_too_many_attempts">Trop de tentatives infructueuses. Réessayez dans %1$s minute(s).</string>
</resources>
  • Cada texto tem um NOME; o código reconhece apenas esse nome: [R.string.ex21_hello];
  • [%1$s]: o primeiro parâmetro, uma string; [%1$d]: um inteiro;
  • [<plurals>]: um texto plural, com uma forma por “categoria” de idioma ([one], [many], [other]...) : [Android] conhece as regras de cada idioma;
  • [C\'est]: o apóstrofo deve ser precedido de uma barra invertida.

O arquivo padrão, [res/values/strings.xml] (inglês): os mesmos nomes, na pasta sem sufixo. [Android] seleciona o arquivo conforme o idioma do aplicativo:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/values/strings.xml - os textos do aplicativo, em INGLÊS
     (o idioma padrão). Mesmos nomes que em res/values-fr/strings.xml;
     um texto ausente aqui estaria ausente em todos os idiomas.
     ===================================================================== -->
<resources>
    <string name="app_name">Kotlin examples</string>

    <string name="ex21_title">Example 21 - two languages</string>
    <string name="ex21_hello">Hello %1$s!</string>
    <string name="ex21_today">Today is %1$s.</string>
    <string name="ex21_price">A consultation costs %1$s.</string>
    <string name="ex21_no_appointment">no appointment</string>
    <plurals name="ex21_appointments">
        <item quantity="one">one appointment</item>
        <item quantity="other">%1$d appointments</item>
    </plurals>
    <string name="ex21_add">Add an appointment</string>
    <string name="ex21_remove">Remove one</string>
    <string name="ex21_calendar">Open the calendar</string>
    <string name="ex21_server_title">Translating a server response</string>
    <string name="ex21_server_explanation">The RdvMedecins server only sends keys. The client translates them:</string>
    <string name="errors_login_taken">This login is already used by another account.</string>
    <string name="errors_too_many_attempts">Too many failed attempts. Try again in %1$s minute(s).</string>
</resources>

Os idiomas do aplicativo são declarados em [res/xml/locales_config.xml], que é referenciado pelo manifesto ([android:localeConfig]):

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/xml/locales_config.xml - os idiomas do aplicativo (exemplo 21)
     ............................................................................
     Declarado em AndroidManifest.xml (android:localeConfig). Desde o
     Android 13, o usuário também pode escolher o idioma de CADA
     aplicativo nas configurações do celular: Configurações > Sistema >
     Idiomas > Idiomas dos apps.
     ===================================================================== -->
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="fr" />
    <locale android:name="en" />
</locale-config>

A partir do [Android] 13, o usuário pode então selecionar o idioma do aplicativo nas configurações do celular. O código do exemplo:

// =========================================================================
// ex21/Ex21Activity.kt - um aplicativo em dois idiomas
// -------------------------------------------------------------------------
// O jeito Android:
//   - os TEXTOS do aplicativo são RECURSOS: um arquivo
//     res/values/strings.xml (o idioma padrão, aqui o inglês) e um
//     arquivo por tradução (res/values-fr/strings.xml). Cada texto tem um
//     nome; o código só conhece esse nome (R.string.ex21_hello), e o
//     Android escolhe o arquivo de acordo com o idioma do aplicativo;
//   - stringResource(R.string.ex21_hello, "Marie"): o texto, cujos
//     parâmetros (%1$s) são substituídos; pluralStringResource: um texto
//     no plural, cuja forma segue as regras do idioma;
//   - o idioma do aplicativo: o do celular... ou o que o
//     aplicativo escolhe por conta própria, AppCompatDelegate.setApplicationLocales.
//     O Android então RECRIA a activity, no novo idioma: os textos,
//     as datas, os valores monetários e os textos do próprio Android (o
//     calendário, seus botões).
// O servidor RdvMedecins, por sua vez, só retorna CHAVES ("ERRORS.LOGIN_TAKEN"):
// elas são associadas aos recursos por uma tabela (serverKeys).
// A activity é uma AppCompatActivity: a classe de activity que pode
// aplicar o idioma escolhido, mesmo nas versões do Android anteriores
// à 13.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex21

import android.os.Bundle
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.appcompat.app.AppCompatActivity
import androidx.appcompat.app.AppCompatDelegate
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.DateRange
import androidx.compose.material3.Card
import androidx.compose.material3.DatePicker
import androidx.compose.material3.DatePickerDialog
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.SegmentedButton
import androidx.compose.material3.SegmentedButtonDefaults
import androidx.compose.material3.SingleChoiceSegmentedButtonRow
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.rememberDatePickerState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableIntStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalConfiguration
import androidx.compose.ui.res.pluralStringResource
import androidx.compose.ui.res.stringResource
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.core.os.LocaleListCompat
import fr.stahe.examples.R
import fr.stahe.examples.common.ExamplePage
import fr.stahe.examples.common.ExamplesTheme
import java.text.NumberFormat
import java.time.LocalDate
import java.time.format.DateTimeFormatter
import java.time.format.FormatStyle
import java.util.Currency

val languages = listOf("fr", "en")

// o que o servidor RdvMedecins retornaria (cf. capítulo sobre a caixa-preta)
data class ServerResponse(val statusCode: Int, val key: String, val params: Map<String, String>)

val serverResponses = listOf(
    ServerResponse(409, "ERRORS.LOGIN_TAKEN", emptyMap()),
    ServerResponse(429, "ERRORS.TOO_MANY_ATTEMPTS", mapOf("minutes" to "15")),
)

// a chave do servidor -> o recurso que a traduz
val serverKeys = mapOf(
    "ERRORS.LOGIN_TAKEN" to R.string.errors_login_taken,
    "ERRORS.TOO_MANY_ATTEMPTS" to R.string.errors_too_many_attempts,
)

class Ex21Activity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { TranslatedPage() } }
    }
}

// escolhendo o idioma do aplicativo: o Android o armazena e recria a activity
fun changeLanguage(language: String) {
    AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(language))
}

@Composable
fun TranslatedPage() {
    // rememberSaveable: a contagem sobrevive à recriação da activity
    var count by rememberSaveable { mutableIntStateOf(2) }
    var calendarOpen by rememberSaveable { mutableStateOf(false) }
    // o idioma ATUAL: o da configuração da activity
    val locale = LocalConfiguration.current.locales[0]
    // formatadores no idioma atual
    val date = LocalDate.now().format(DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(locale))
    val price = NumberFormat.getCurrencyInstance(locale).apply { currency = Currency.getInstance("EUR") }.format(1234.5)

    ExamplePage(
        title = stringResource(R.string.ex21_title),
        // os idiomas: botões "segmentados", na barra superior
        actions = {
            SingleChoiceSegmentedButtonRow(Modifier.padding(end = 8.dp).width(120.dp)) {
                languages.forEachIndexed { i, l ->
                    SegmentedButton(
                        selected = locale.language == l,
                        onClick = { changeLanguage(l) },
                        shape = SegmentedButtonDefaults.itemShape(i, languages.size),
                        icon = {},
                    ) { Text(l.uppercase()) }
                }
            }
        },
    ) {
        Card(Modifier.fillMaxWidth()) {
            Column(Modifier.padding(12.dp)) {
                Text(stringResource(R.string.ex21_hello, "Marie"))
                Text(stringResource(R.string.ex21_today, date))
                Text(stringResource(R.string.ex21_price, price))
                Spacer(Modifier.height(8.dp))
                // o plural: a categoria "zero" não existe nem em francês nem em
                // inglês (0 é "one" em francês, "other" em inglês): 0 é
                // tratado separadamente
                Text(
                    if (count == 0) stringResource(R.string.ex21_no_appointment) else pluralStringResource(R.plurals.ex21_appointments, count, count),
                    fontWeight = FontWeight.Bold,
                )
                FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
                    TextButton(onClick = { count++ }) { Text(stringResource(R.string.ex21_add)) }
                    TextButton(onClick = { count-- }, enabled = count > 0) { Text(stringResource(R.string.ex21_remove)) }
                }
                // o calendário Material: seus textos seguem o idioma do aplicativo
                OutlinedButton(onClick = { calendarOpen = true }) {
                    Icon(Icons.Default.DateRange, contentDescription = null)
                    Spacer(Modifier.width(8.dp))
                    Text(stringResource(R.string.ex21_calendar))
                }
            }
        }
        Card(Modifier.fillMaxWidth()) {
            Column(Modifier.padding(12.dp)) {
                Text(stringResource(R.string.ex21_server_title), style = MaterialTheme.typography.titleSmall)
                Text(stringResource(R.string.ex21_server_explanation))
                Spacer(Modifier.height(8.dp))
                for (r in serverResponses) {
                    Text("${r.statusCode} ${r.key}", fontFamily = FontFamily.Monospace, fontSize = 12.sp)
                    // o recurso da chave; seus parâmetros, em ordem (*: "espalha" o array)
                    val id = serverKeys[r.key]
                    Text("→ " + if (id == null) r.key else stringResource(id, *r.params.values.toTypedArray()))
                    Spacer(Modifier.height(6.dp))
                }
            }
        }
    }

    if (calendarOpen) {
        val state = rememberDatePickerState()
        DatePickerDialog(
            onDismissRequest = { calendarOpen = false },
            // os textos OK / Cancelar do próprio Android, no idioma do aplicativo
            confirmButton = { TextButton(onClick = { calendarOpen = false }) { Text(stringResource(android.R.string.ok)) } },
            dismissButton = { TextButton(onClick = { calendarOpen = false }) { Text(stringResource(android.R.string.cancel)) } },
        ) {
            DatePicker(state = state)
        }
    }
}
  • Linhas 92–94: o servidor RdvMedecins retorna apenas CHAVES (["ERRORS.LOGIN_TAKEN"]); elas são associadas a recursos por meio de uma tabela;
  • linha 97: uma [AppCompatActivity]: a classe de activity que sabe aplicar o idioma selecionado, mesmo antes do [Android] 13;
  • linhas 106–107: selecionam o idioma do APLICATIVO (não o idioma do celular): o [Android] o armazena e RECRIA a activity no novo idioma. Antes do [Android] 13, a biblioteca [AppCompat] o armazena (o serviço [AppLocalesMetadataHolderService] no manifesto, [autoStoreLocales]);
  • linhas 116–119: o idioma atual, que é o idioma especificado na configuração da activity, e os formatadores de data e de valor para esse idioma;
  • linha 122: [stringResource(R.string.ex21_title)]: o texto no idioma atual;
  • linhas 10–11: parâmetros e uma forma plural ([pluralStringResource]): como a categoria [zero] não existe nem em francês nem em inglês, o 0 é tratado separadamente;
  • linhas 170–171: a tradução de uma chave do servidor, junto com seus parâmetros ([*] “espalha” um array em uma lista de parâmetros);
  • linhas 180–184: o texto do próprio [Android] ([android.R.string.ok]) e o do calendário também seguem o idioma do aplicativo.

Image

Image

Image

O número de consultas persiste entre as mudanças de idioma graças a [rememberSaveable]: a activity, no entanto, foi destruída e recriada.