Skip to main content

Kotlin Multiplatform i18n: współdzielona lokalizacja na wielu platformach

Napisz tłumaczenia raz we współdzielonym kodzie Kotlin. Udostępnij je w Androidzie, iOS i internecie z prawidłowymi łańcuchami rezerwowymi.

1

Konfigurowanie Gradle dla KMP i18n

Dodaj zależności i18n do zestawu źródeł commonMain współdzielonego modułu. Wybierz moko-resources dla tekstów zdefiniowanych w XML, Lyricist dla bezpiecznych typowo tekstów Compose albo obie biblioteki. kmp-localechain doda do każdego rozwiązania inteligentny mechanizm rezerwowy.

build.gradle.kts
// build.gradle.kts (shared module)
plugins {
    kotlin("multiplatform")
    id("com.android.library")
}

kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()
    js(IR) { browser(); nodejs() }

    sourceSets {
        val commonMain by getting {
            dependencies {
                // Option A: moko-resources (code-gen from XML)
                implementation("dev.icerock.moko:resources:0.24.4")

                // Option B: Lyricist (type-safe Compose strings)
                implementation("cafe.adriel.lyricist:lyricist:1.7.0")

                // Locale fallback chains (works with any library)
                implementation("com.i18nagent:locale-chain-kmp:0.1.0")
            }
        }
    }
}
Wszystkie trzy biblioteki są publikowane w Maven Central. Dodaj je do zależności commonMain, aby były dostępne dla każdego celu: Androida, iOS i JS.
2

Definiowanie współdzielonych typów tekstu

Utwórz w commonMain klasy danych Kotlin zawierające wszystkie tłumaczone teksty. Stanowią one jedno źródło referencyjne — każda platforma odczytuje te same bezpieczne typowo definicje. Bez zduplikowanych plików i rozbieżności między platformami.

commonMain/.../Strings.kt
// commonMain/kotlin/com/myapp/Strings.kt
package com.myapp.i18n

/**
 * Shared string definitions — the single source of truth.
 * Each platform reads from the same keys.
 */
data class AppStrings(
    val greeting: String,
    val farewell: String,
    val itemCount: (count: Int) -> String,
    val nav: NavStrings,
)

data class NavStrings(
    val home: String,
    val settings: String,
    val about: String,
)

// English defaults
val EnStrings = AppStrings(
    greeting = "Hello!",
    farewell = "Goodbye!",
    itemCount = { count ->
        if (count == 1) "$count item" else "$count items"
    },
    nav = NavStrings(
        home = "Home",
        settings = "Settings",
        about = "About",
    ),
)

// Japanese
val JaStrings = AppStrings(
    greeting = "こんにちは!",
    farewell = "さようなら!",
    itemCount = { count -> "${count}個のアイテム" },
    nav = NavStrings(
        home = "ホーム",
        settings = "設定",
        about = "概要",
    ),
)

// Add more locales following the same pattern: DeStrings, EsStrings, etc.
Dla liczby mnogiej używaj właściwości lambda zamiast osobnych kluczy liczby pojedynczej i mnogiej. Lambda otrzymuje wartość i zwraca odpowiednią formę. Logika pozostaje w Kotlinie, gdzie może ją sprawdzić kompilator.
3

Podłączanie Androida

W androidMain zaimplementuj wzorzec expect/actual, aby odczytać język urządzenia przez java.util.Locale. Android może używać współdzielonych tekstów Kotlin w logice biznesowej obok standardowego values/strings.xml dla elementów systemowych takich jak powiadomienia i widżety.

androidMain/.../StringProvider.kt
// androidMain/kotlin/com/myapp/StringProvider.kt
package com.myapp.i18n

import java.util.Locale

actual fun currentLocale(): String =
    Locale.getDefault().toLanguageTag()  // e.g. "pt-BR"

// Android can also use standard resources/values-*/strings.xml
// alongside the shared Kotlin definitions.
// Use shared strings for business logic, XML for system UI.

// In your Activity or Compose screen:
@Composable
fun GreetingScreen() {
    val strings = rememberStrings()  // resolves via locale
    Text(text = strings.greeting)
    Text(text = strings.itemCount(cartSize))
}
Locale.getDefault().toLanguageTag() zwraca znaczniki IETF takie jak "pt-BR", ale starsze API niektórych wersji Androida zwracają "pt-rBR". Aby uzyskać spójne wyniki, zawsze używaj toLanguageTag() (API 21+).
4

Podłączanie iOS

W iosMain zaimplementuj currentLocale() przy użyciu NSLocale z Foundation. Współdzielony framework KMP eksportuje definicje tekstów do Swift, dzięki czemu widoki SwiftUI mogą wywoływać je bezpośrednio przez wygenerowany framework Kotlin.

iosMain/.../StringProvider.kt
// iosMain/kotlin/com/myapp/StringProvider.kt
package com.myapp.i18n

import platform.Foundation.NSLocale
import platform.Foundation.currentLocale
import platform.Foundation.languageCode
import platform.Foundation.countryCode

actual fun currentLocale(): String {
    val locale = NSLocale.currentLocale
    val lang = locale.languageCode
    val country = locale.countryCode
    return if (country != null) "$lang-$country" else lang
}

// In SwiftUI (via KMP exported framework):
// let strings = StringProviderKt.stringsFor(locale: "ja")
// Text(strings.greeting)
Podczas eksportowania frameworka KMP do Xcode pamiętaj o module dostawcy tekstów. Uwzględnij pakiet i18n w konfiguracji Podspec lub XCFramework, aby kod Swift mógł go importować.
5

Podłączanie JS/przeglądarki

W jsMain odczytaj język przeglądarki z window.navigator.language. Rozwiązanie działa zarówno dla aplikacji internetowych Kotlin/JS, jak i celów Compose for Web. Te same współdzielone teksty są renderowane w przeglądarce bez duplikacji.

jsMain/.../StringProvider.kt
// jsMain/kotlin/com/myapp/StringProvider.kt
package com.myapp.i18n

import kotlinx.browser.window

actual fun currentLocale(): String =
    window.navigator.language  // e.g. "en-US", "pt-BR"

// In a Kotlin/JS or Compose for Web app:
fun main() {
    val locale = currentLocale()
    val strings = stringsFor(locale)
    document.getElementById("greeting")?.textContent = strings.greeting
}
Dla Kotlin/JS po stronie serwera (Node.js) odczytaj język z nagłówka Accept-Language albo zmiennej konfiguracji zamiast window.navigator.language.
6

Lyricist dla Compose Multiplatform

Lyricist zapewnia natywne dla Compose podejście do i18n. Oznacz obiekty tekstów adnotacją @LyricistStrings, a biblioteka wygeneruje dostawcę CompositionLocal. Zmieniaj język podczas działania przez languageTag — interfejs automatycznie przeprowadzi rekompozycję.

Lyricist integration
// Using Lyricist for Compose Multiplatform
// build.gradle.kts
plugins {
    id("cafe.adriel.lyricist") version "1.7.0"
}

// Define strings with @LyricistStrings annotation
@LyricistStrings(languageTag = Locales.EN, default = true)
val EnStrings = Strings(
    greeting = "Hello!",
    farewell = "Goodbye!",
    itemCount = { count ->
        if (count == 1) "$count item" else "$count items"
    },
)

@LyricistStrings(languageTag = Locales.JA)
val JaStrings = Strings(
    greeting = "こんにちは!",
    farewell = "さようなら!",
    itemCount = { count -> "${count}個のアイテム" },
)

// In your Compose UI
@Composable
fun App() {
    // Lyricist provides the strings via CompositionLocal
    ProvideStrings {
        val lyricist = LocalStrings.current
        Text(text = lyricist.greeting)
    }
}

// Switch language at runtime
val lyricist = rememberLyricist(
    defaultLanguageTag = Locales.EN,
)
lyricist.languageTag = Locales.JA  // UI recomposes automatically
Lyricist obsługuje interpolację tekstów, liczbę mnogą za pomocą lambd oraz zagnieżdżone grupy. Działa na Androidzie, iOS przez Compose for iOS, Desktopie i Webie.
7

moko-resources dla tekstów XML

moko-resources używa plików XML w stylu Androida jako źródła referencyjnego i generuje bezpieczne typowo akcesory. Zdefiniuj teksty angielskie w commonMain/resources/MR/base/ i dodaj katalogi językowe. Wygenerowany obiekt MR zapewnia dostęp sprawdzany podczas kompilacji.

moko-resources setup
// Using moko-resources for XML-based string management
// build.gradle.kts
plugins {
    id("dev.icerock.mobile.multiplatform-resources") version "0.24.4"
}

multiplatformResources {
    resourcesPackage.set("com.myapp")
}

// commonMain/resources/MR/base/strings.xml (English - default)
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="greeting">Hello!</string>
    <string name="farewell">Goodbye!</string>
    <plurals name="item_count">
        <item quantity="one">%d item</item>
        <item quantity="other">%d items</item>
    </plurals>
</resources>

// commonMain/resources/MR/ja/strings.xml (Japanese)
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="greeting">こんにちは!</string>
    <string name="farewell">さようなら!</string>
    <plurals name="item_count">
        <item quantity="other">%d個のアイテム</item>
    </plurals>
</resources>

// Usage in shared Kotlin code
val greeting = MR.strings.greeting.desc()
val items = MR.plurals.item_count.format(count)
moko-resources wymaga wtyczki Gradle do generowania kodu. Jeśli widoczny jest błąd 'Unresolved reference: MR', najpierw uruchom synchronizację Gradle. Generowanie kodu musi się zakończyć, zanim środowisko rozpozna akcesory MR.
8

Inteligentny łańcuch rezerwowy z kmp-localechain

Biblioteki i18n dla KMP nie oferują konfigurowalnych łańcuchów rezerwowych. Gdy brakuje pt-BR, całkowicie pomijają pt-PT i wyświetlają angielski. kmp-localechain rozwiązuje problem za pomocą niezależnego narzędzia do scalania wiadomości. Przyjmuje płaskie wiadomości Map&lt;String, String&gt; dla każdego języka i zwraca scaloną mapę zgodną z priorytetem łańcucha.

LocaleChain usage
// Using kmp-localechain for smart locale fallback
import com.i18nagent.localechain.LocaleChain

// 1. Configure once at app startup
LocaleChain.configure()  // uses built-in fallback chains

// 2. Load your messages as flat maps
val messages = mapOf(
    "en" to mapOf("greeting" to "Hello", "farewell" to "Goodbye"),
    "pt" to mapOf("greeting" to "Olá", "farewell" to "Adeus"),
    "pt-PT" to mapOf("greeting" to "Olá (PT)"),
    "pt-BR" to mapOf("greeting" to "Oi"),
)

// 3. Resolve with chain priority
val resolved = LocaleChain.resolve("pt-BR", messages)
// "greeting" -> "Oi"       (from pt-BR, most specific)
// "farewell" -> "Adeus"    (from pt, next in chain)

// Without LocaleChain, pt-BR users would see English "Goodbye"
// because pt-BR has no "farewell" key.
Custom configuration
// Custom fallback configuration
LocaleChain.configure(
    defaultLocale = "en",
    overrides = mapOf(
        "es-MX" to listOf("es-419", "es"),
        "fr-CA" to listOf("fr"),
    )
)

// Inspect any chain
LocaleChain.chainFor("pt-BR")
// Returns: ["pt-BR", "pt-PT", "pt", "en"]

// Async resolve (lazy loading from network/disk)
val resolved = LocaleChain.resolve("pt-BR") { localeTag ->
    api.fetchMessages(localeTag)  // returns Map<String, String>?
}
kmp-localechain działa z płaskimi mapami Map&lt;String, String&gt;. Zagnieżdżone wiadomości należy spłaszczyć przed przekazaniem do resolve(). Biblioteka nie obsługuje głębokiego scalania zagnieżdżonych struktur.
9

Automatyzacja tłumaczeń

Po skonfigurowaniu KMP i18n zautomatyzuj tłumaczenia za pomocą AI. Tłumacz współdzielone pliki tekstów — klasy danych Kotlin, zasoby XML lub JSON — bezpośrednio ze środowiska programistycznego albo pipeline CI/CD.

Terminal
# Translate your shared string files with i18n Agent
# Works with JSON, XML (moko-resources), or any i18n format

# From your IDE (Claude Code, Cursor, VS Code):
> Translate commonMain/resources/MR/base/strings.xml to Japanese, German, and Spanish

✓ MR/ja/strings.xml created (1.2s)
✓ MR/de/strings.xml created (1.1s)
✓ MR/es/strings.xml created (1.3s)

# Or use the CLI in CI/CD:
npx i18n-agent translate resources/base/strings.xml --lang ja,de,es
Tłumacz przyrostowo. Po dodaniu nowych kluczy do angielskiego źródła przetłumacz tylko różnicę. Pozwoli to zachować tłumaczenia sprawdzone przez człowieka i uniknąć ponownego generowania całych plików.

Automatyczna kontrola jakości tłumaczeń

Wykryj brakujące klucze i uszkodzone symbole zastępcze przed wydaniem za pomocą i18n-validate. Przetestuj interfejs przy użyciu pseudotłumaczeń z i18n-pseudo, zanim pojawią się właściwe tłumaczenia.

Częste pułapki

Niezgodność expect/actual

Każda deklaracja expect w commonMain wymaga implementacji actual dla każdego celu: androidMain, iosMain i jsMain. Po dodaniu nowej platformy kompilator będzie zgłaszał błąd do czasu utworzenia implementacji. Użyj szybkich poprawek środowiska, aby wygenerować szkielety.

Liczba mnoga zakodowana na stałe

Nigdy nie używaj count == 1 do wykrywania liczby pojedynczej. Francuski traktuje 0 jak liczbę pojedynczą, arabski ma sześć form, a rosyjski używa różnych form dla liczb kończących się na 1, 2-4 i 5-20. Stosuj biblioteki zgodne z CLDR, na przykład moko-resources. Możesz też użyć jawnych lambd dla każdego języka.

Zagnieżdżone mapy w kmp-localechain

kmp-localechain działa na płaskich Map&lt;String, String&gt;. Przekazanie zagnieżdżonych map uniemożliwia prawidłowe scalenie kluczy wewnętrznych. Przed wywołaniem resolve() spłaszcz wiadomości, używając kluczy w notacji kropkowej, na przykład "nav.home".

Brak wygenerowanego kodu po dodaniu moko-resources

Obiekt MR jest generowany przez wtyczkę Gradle. Po dodaniu tekstów moko-resources uruchom synchronizację Gradle przed użyciem MR.strings.* w kodzie. Jeśli środowisko nadal pokazuje błędy, użyj Build > Rebuild Project.

Zalecana struktura projektu

Project Structure
my-kmp-app/
├── shared/
│   ├── build.gradle.kts
│   └── src/
│       ├── commonMain/
│       │   ├── kotlin/com/myapp/i18n/
│       │   │   ├── Strings.kt           # Shared string definitions
│       │   │   ├── StringProvider.kt     # expect fun currentLocale()
│       │   │   └── LocaleSetup.kt       # LocaleChain configuration
│       │   └── resources/MR/            # moko-resources XML (optional)
│       │       ├── base/strings.xml     # English (default)
│       │       ├── ja/strings.xml
│       │       ├── de/strings.xml
│       │       └── es/strings.xml
│       ├── androidMain/
│       │   └── kotlin/com/myapp/i18n/
│       │       └── StringProvider.kt     # actual fun currentLocale()
│       ├── iosMain/
│       │   └── kotlin/com/myapp/i18n/
│       │       └── StringProvider.kt     # actual fun currentLocale()
│       └── jsMain/
│           └── kotlin/com/myapp/i18n/
│               └── StringProvider.kt     # actual fun currentLocale()
├── androidApp/
│   └── src/main/res/values/strings.xml   # Android-specific overrides
├── iosApp/
│   └── iosApp/Localizable.strings        # iOS-specific overrides
└── settings.gradle.kts

Wypróbuj i18n Agent

Upuść tutaj plik tłumaczenia

JSON, YAML, PO, XML, CSV, Markdown, Properties

lub kliknij, aby go wybrać

Języki docelowe

Rejestracja nie jest wymaganaNatychmiastowa wycena

Częste pytania