Lokalizacja Flutter: pliki ARB, intl i gen-l10n w praktyce

Używaj jednego generatora lokalizacji i jasno określ jego lokalizacje wejściowe i wyjściowe. Poniższy przykład zakłada istniejącą aplikację Flutter z własnymi ograniczeniami SDK i standardową konfiguracją projektu.

Scal odpowiednie wpisy z pubspec.yaml; nie duplikuj sekcji dependencies ani flutter:

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any

flutter:
  generate: true

Rozwiąż zależności za pomocą flutter pub get. Wpis intl: any jest zgodny z oficjalnym wzorcem konfiguracji i pozwala mechanizmowi rozwiązywania zależności wybrać wersję zgodną z Flutter SDK; zachowaj plik lockfile aplikacji i standardowy proces przeglądu zależności.

Utwórz l10n.yaml w katalogu głównym projektu:

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

Do konfiguracji zależnej od SDK używaj aktualnego przewodnika po internacjonalizacji Flutter. W nowoczesnym procesie wygenerowane pliki lokalizacyjne należą do drzewa źródłowego aplikacji. Przykład importuje z lib/l10n; nie kopiuj do nowej konfiguracji starego, syntetycznego importu package:flutter_gen. Zobacz notę o migracji generowanego kodu źródłowego.

Utwórz lib/l10n/app_en.arb:

{
  "@@locale": "en",
  "appTitle": "Reading room",
  "@appTitle": {
    "description": "Title of the sample reading application"
  },
  "welcomeName": "Welcome, {name}",
  "@welcomeName": {
    "description": "Greeting on the home screen",
    "placeholders": {
      "name": {"type": "String", "example": "Sam"}
    }
  },
  "savedBooks": "{count, plural, =0{No saved books} one{1 saved book} other{{count} saved books}}",
  "@savedBooks": {
    "description": "Number of books saved to the user's library",
    "placeholders": {
      "count": {"type": "int"}
    }
  },
  "readingState": "{state, select, active{Reading now} paused{Reading paused} other{Ready to read}}",
  "@readingState": {
    "description": "Reading status; state is active, paused or another value",
    "placeholders": {
      "state": {"type": "String"}
    }
  }
}

Utwórz lib/l10n/app_es.arb:

{
  "@@locale": "es",
  "appTitle": "Sala de lectura",
  "welcomeName": "Te damos la bienvenida, {name}",
  "savedBooks": "{count, plural, =0{No hay libros guardados} one{1 libro guardado} other{{count} libros guardados}}",
  "readingState": "{state, select, active{Leyendo ahora} paused{Lectura en pausa} other{Todo listo para leer}}"
}

Szablon zawiera metadane placeholderów używane przez generator. Zlokalizowany plik zachowuje klucze komunikatów, nazwy placeholderów i identyfikatory select, zmieniając jedynie sformułowania widoczne dla użytkownika. Te hiszpańskie przykłady ilustrują mechanikę; tekst produkcyjny powinien przejść natywną weryfikację w rzeczywistym kontekście produktu.

Uruchom flutter gen-l10n po dodaniu lub zmianie zasobów. Traktuj błędy generatora jako konkretne problemy z zasobami i rozwiąż je przed włączeniem plików do wydania.

Poniższy przykład należy umieścić w lib/main.dart po wygenerowaniu:

import 'package:flutter/material.dart';
import 'l10n/app_localizations.dart';

void main() => runApp(const ReadingApp());

class ReadingApp extends StatelessWidget {
  const ReadingApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      supportedLocales: AppLocalizations.supportedLocales,
      home: const ReadingHome(),
    );
  }
}

class ReadingHome extends StatelessWidget {
  const ReadingHome({super.key});

  @override
  Widget build(BuildContext context) {
    final messages = AppLocalizations.of(context)!;
    return Scaffold(
      appBar: AppBar(title: Text(messages.appTitle)),
      body: Padding(
        padding: const EdgeInsetsDirectional.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text(messages.welcomeName('Sam')),
            Text(messages.savedBooks(3)),
            Text(messages.readingState('active')),
          ],
        ),
      ),
    );
  }
}

Wygenerowane API sprawia, że różnica między zwykłym komunikatem a komunikatem z argumentami jest widoczna w kodzie. Do appTitle odwołujemy się jak do wartości; welcomeName, savedBooks i readingState otrzymują wartości potrzebne do zbudowania komunikatów.

Przed wyborem zapoznaj się z aktualną dokumentacją easy_localization i dokumentacją GetX. Przetestuj zachowanie zastępcze, parametry, kategorie liczby mnogiej i procesy ekstrakcji na swoich rzeczywistych komunikatach. Wygodne API dla angielskich tekstów nie dowodzi obsługi każdego języka, który planujesz wydać.

intl nie jest konkurencyjną platformą do zarządzania tłumaczeniami. Dostarcza narzędzia do internacjonalizacji używane w procesach lokalizacji. gen-l10n generuje akcesory aplikacji z zasobów ARB. Osobny pakiet intl_utils również generuje kod lokalizacyjny, ale jego strona była oznaczona jako wycofana w chwili sprawdzenia 30 października 2026 r. Sprawdź status utrzymania, zanim użyjesz go w nowym projekcie.

Korzystaj z praktycznej macierzy testów:

FAQ Flutter web opisuje nacisk na doświadczenia aplikacyjne i zaleca podejście dokumentowe dla statycznych treści webowych z dużą ilością tekstu. Rozważ osobne strony marketingowe, pomocy i redakcyjne oparte na HTML, jeśli mają one dobrze radzić sobie w wynikach organicznych.

Utrzymuj spójną terminologię między aplikacją a tymi stronami publicznymi. Użytkownik z wyszukiwarki powinien rozpoznać nazwę funkcji po przejściu ze zlokalizowanej strony docelowej do aplikacji, nawet jeśli obie powierzchnie korzystają z różnych systemów renderowania.

Udokumentowane formaty projektów oprogramowania w Smartcat obejmują import JSON, YAML, Android XML, iOS .strings i LocJSON. Dokumentacja przeanalizowana na potrzeby tego przewodnika nie potwierdza natywnej obsługi ARB ani przetestowanego procesu konwersji ARB do JSON. Nie zakładaj, że zmiana rozszerzenia pliku dowodzi zgodności. Zobacz dokumentację projektów oprogramowania.

Traktuj poniższe jako proponowaną procedurę weryfikacji do przeprowadzenia z zespołem wdrożeniowym, a nie jako już przetestowany przepis na konektor: