Skip to content

7. 国际化

7.1. 示例 21:双语应用

[Flutter] 使用 ARB 文件,或 [easy_localization] 包的 JSON 文件。[Android] 有自己的、内置于系统的方法:应用的文本就是资源。[res/values/strings.xml] 文件包含默认语言(此处为英语)的文本;每种翻译是一个同名文件,放在后缀为语言代码的文件夹中。法语翻译为 [res/values-fr/strings.xml]:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/values-fr/strings.xml - the texts of the application, in FRENCH
     (the translation). The default language, English, is in
     res/values/strings.xml: Android chooses the file according to the
     language of the application (cf. example 21).
     ===================================================================== -->
<resources>
    <string name="app_name">Exemples Kotlin</string>

    <!-- 示例 21 -->
    <string name="ex21_title">Exemple 21 - deux langues</string>
    <!-- %1$s:第一个参数,一个字符串 -->
    <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>
    <!-- a plural text: one form per "category" of the language;
         %1$d: the first parameter, an integer -->
    <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>
  • 每段文本都有一个名称;代码只认这个名称:[R.string.ex21_hello];
  • [%1$s]:第一个参数,一个字符串;[%1$d]:一个整数;
  • [<plurals>]:复数文本,每种语言的每个“类别”对应一种形式([one]、[many]、[other] 等):[Android] 了解每种语言的规则;
  • [C\'est]:撇号前面必须加一个反斜杠。

默认文件 [res/values/strings.xml](英语):名称相同,位于不带后缀的文件夹中。[Android] 根据应用的语言选择文件:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/values/strings.xml - the texts of the application, in ENGLISH
     (the default language). Same names as in res/values-fr/strings.xml;
     a text missing from here would be missing in every language.
     ===================================================================== -->
<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>

应用支持的语言在 [res/xml/locales_config.xml] 中声明,清单通过 [android:localeConfig] 引用它:

<?xml version="1.0" encoding="utf-8"?>
<!-- =====================================================================
     res/xml/locales_config.xml - the languages of the application (example 21)
     ............................................................................
     Declared in AndroidManifest.xml (android:localeConfig). Since
     Android 13, the user can also choose the language of EACH
     application in the phone settings: Settings > System >
     Languages > App languages.
     ===================================================================== -->
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
    <locale android:name="fr" />
    <locale android:name="en" />
</locale-config>

从 [Android] 13 开始,用户随后可以在手机设置中选择应用语言。示例的代码:

// =========================================================================
// ex21/Ex21Activity.kt - 一个双语应用
// -------------------------------------------------------------------------
// Android 的方式:
//   - 应用的文本是资源:一个文件
//     res/values/strings.xml(默认语言,这里是英语),以及每种翻译一个
//     文件(res/values-fr/strings.xml)。每段文本有一个
//     名称;代码只认这个名称(R.string.ex21_hello),
//     Android 根据应用的语言选择文件;
//   - stringResource(R.string.ex21_hello, "Marie"):该文本,其
//     参数(%1$s)会被替换;pluralStringResource:复数
//     文本,其形式遵循语言的规则;
//   - 应用的语言:手机的语言……或者由
//     应用自己选择的语言,通过 AppCompatDelegate.setApplicationLocales。
//     随后 Android 会用新语言重新创建 Activity:文本、
//     日期、金额,以及 Android 自身的文本(
//     日历及其按钮)。
// 至于 RdvMedecins 服务器,它只返回键(“ERRORS.LOGIN_TAKEN”):
// 它们通过一张表(serverKeys)与资源关联。
// 该 Activity 是一个 AppCompatActivity:这种 Activity 类能够
// 应用所选语言,即使在 13 之前的 Android
// 版本上也是如此。
// =========================================================================
@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")

// RdvMedecins 服务器会返回的内容(参见关于黑盒的章节)
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")),
)

// 服务器的键 -> 翻译它的资源
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() } }
    }
}

// 选择应用的语言:Android 会存储它,并重新创建 Activity
fun changeLanguage(language: String) {
    AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags(language))
}

@Composable
fun TranslatedPage() {
    // rememberSaveable:计数在 Activity 重新创建后依然保留
    var count by rememberSaveable { mutableIntStateOf(2) }
    var calendarOpen by rememberSaveable { mutableStateOf(false) }
    // 当前语言:Activity 配置中的语言
    val locale = LocalConfiguration.current.locales[0]
    // 当前语言的格式化器
    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),
        // 语言:“分段”按钮,位于顶部栏中
        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))
                // 复数:法语和英语中都不存在“zero”类别
                // (法语中 0 属于“one”,英语中属于“other”):0 被
                // 单独处理
                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)) }
                }
                // Material 日历:它的文本遵循应用的语言
                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)
                    // 该键对应的资源;它的参数,按顺序排列(*:“展开”数组)
                    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 },
            // Android 自身的 OK / Cancel 文本,使用应用的语言
            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)
        }
    }
}
  • 第 92–94 行:RdvMedecins 服务器只返回键(["ERRORS.LOGIN_TAKEN"]);通过一张表把它们映射到资源;
  • 第 97 行:一个 [AppCompatActivity]:知道如何应用所选语言的 Activity 类,甚至在 [Android] 13 之前也适用;
  • 第 106–107 行:为应用选择语言(而不是手机的语言):[Android] 会存储它,并用新语言重新创建 Activity。在 [Android] 13 之前,由 [AppCompat] 库负责存储它(清单中的 [AppLocalesMetadataHolderService] 服务,[autoStoreLocales]);
  • 第 116–119 行:当前语言,即 Activity 配置中指定的语言,以及该语言的日期和金额格式化器;
  • 第 122 行:[stringResource(R.string.ex21_title)]:当前语言的文本;
  • 第 10–11 行:参数和复数形式([pluralStringResource]):由于法语和英语都不存在类别 [zero],因此 0 被单独处理;
  • 第 170–171 行:服务器键的翻译,连同它的参数([*] 将数组“展开”为参数列表);
  • 第 180–184 行:[Android] 自身的文本([android.R.string.ok])和日历的文本也遵循应用的语言。

Image

Image

Image

得益于 [rememberSaveable],预约的数量在语言切换时得以保留:而 Activity 实际上已经被销毁并重新创建。