Przetłumacz swoją aplikację Expo i React Native | Internacjonalizacja (i18n)

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna, open-source’owa biblioteka do internacjonalizacji (i18n), która upraszcza wsparcie wielojęzyczne w nowoczesnych aplikacjach. Działa w wielu środowiskach JavaScript/TypeScript, w tym w React Native (poprzez pakiet react-intlayer).

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami za pomocą deklaratywnych słowników na poziomie komponentu.
• Zapewnić wsparcie TypeScript dzięki automatycznie generowanym typom.
• Dynamicznie lokalizować zawartość, w tym łańcuchy UI (a w React dla weba może także lokalizować metadane HTML itd.).
• Korzystać z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie lokalizacji.

Krok 1: Instalacja zależności

Zobacz Szablon aplikacji na GitHub.

W swoim projekcie React Native zainstaluj następujące pakiety:

npm install intlayer react-intlayernpm install --save-dev react-native-intlayernpx intlayer init

Pakiety

• intlayer
  Podstawowe narzędzie i18n do konfiguracji, zawartości słownika, generowania typów oraz poleceń CLI.

• react-intlayer
  Integracja z React, która dostarcza dostawców kontekstu oraz hooki React, których użyjesz w React Native do pobierania i przełączania lokalizacji.

• react-native-intlayer
  Integracja z React Native, która dostarcza wtyczkę Metro do integracji Intlayer z bundlerem React Native.

Krok 2: Utwórz konfigurację Intlayer

W katalogu głównym projektu (lub w dowolnym wygodnym miejscu) utwórz plik konfiguracji Intlayer. Może on wyglądać tak:

/**
 * Jeśli typy Locales nie są dostępne, spróbuj ustawić moduleResolution na "bundler" w swoim tsconfig.json
 */
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // ... Dodaj inne potrzebne lokalizacje
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

W ramach tej konfiguracji możesz:

• Skonfigurować swoją listę obsługiwanych lokalizacji.
• Ustawić domyślną lokalizację.
• Później możesz dodać bardziej zaawansowane opcje (np. logi, niestandardowe katalogi z zawartością itp.).
• Zobacz dokumentację konfiguracji Intlayer po więcej informacji.

Krok 3: Dodaj wtyczkę Metro

Metro to bundler dla React Native. Jest to domyślny bundler dla projektów React Native tworzonych za pomocą polecenia react-native init. Aby używać Intlayer z Metro, musisz dodać wtyczkę do pliku metro.config.js:

const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

Uwaga: configMetroIntlayer to funkcja zwracająca promise. Użyj configMetroIntlayerSync, jeśli chcesz użyć jej synchronicznie lub uniknąć IIFE (Immediately Invoked Function Expression). Uwaga: configMetroIntlayerSync nie pozwala na budowanie słowników intlayer podczas uruchamiania serwera

Krok 4: Dodaj dostawcę Intlayer

Aby utrzymać synchronizację języka użytkownika w całej aplikacji, musisz opakować swój komponent root w komponent IntlayerProvider z react-native-intlayer.

Upewnij się, że używasz providera z react-native-intlayer zamiast react-intlayer. Eksport z react-native-intlayer zawiera polyfille dla web API.

Dodatkowo, musisz dodać funkcję intlayerPolyfill do swojego pliku index.js, aby zapewnić prawidłowe działanie Intlayer.

import { Stack } from "expo-router";
import { getLocales } from "expo-localization";
import { IntlayerProvider } from "react-native-intlayer";
import { type FC } from "react";

const getDeviceLocale = () => getLocales()[0]?.languageTag;

const RootLayout: FC = () => {
  return (
    <IntlayerProvider defaultLocale={getDeviceLocale()}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      </Stack>
    </IntlayerProvider>
  );
};

export default RootLayout;

Krok 5: Zadeklaruj swoją zawartość

Utwórz pliki deklaracji zawartości w dowolnym miejscu w swoim projekcie (zwykle w katalogu src/), używając dowolnego z formatów rozszerzeń obsługiwanych przez Intlayer:

• .content.json
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• itd.

Przykład (TypeScript z węzłami TSX dla React Native):

import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";

/**
 * Słownik treści dla naszej domeny "app"
 */
import { t, type Dictionary } from "intlayer";

const homeScreenContent = {
  key: "home-screen",
  content: {
    title: t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    }),
  },
} satisfies Dictionary;

export default homeScreenContent;

Szczegóły dotyczące deklaracji zawartości znajdziesz w dokumentacji Intlayer dotyczącej zawartości.

Krok 4: Użyj Intlayer w swoich komponentach

Użyj hooka useIntlayer w komponentach potomnych, aby uzyskać zlokalizowaną zawartość.

Przykład

import { Image, StyleSheet, Platform } from "react-native";
import { useIntlayer } from "react-intlayer";
import { HelloWave } from "@/components/HelloWave";
import ParallaxScrollView from "@/components/ParallaxScrollView";
import { ThemedText } from "@/components/ThemedText";
import { ThemedView } from "@/components/ThemedView";
import { type FC } from "react";

const HomeScreen = (): FC => {
  const { title, steps } = useIntlayer("home-screen");

  return (
    <ParallaxScrollView
      headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
      headerImage={
        <Image
          source={require("@/assets/images/partial-react-logo.png")}
          style={styles.reactLogo}
        />
      }
    >
      <ThemedView style={styles.titleContainer}>
        <ThemedText type="title">{title}</ThemedText>
        <HelloWave />
      </ThemedView>
    </ParallaxScrollView>
  );
};

const styles = StyleSheet.create({
  titleContainer: {
    flexDirection: "row",
    alignItems: "center",
    gap: 8,
  },
});

export default HomeScreen;

Kiedy używasz content.someKey w właściwościach opartych na łańcuchach znaków (np. title przycisku lub children komponentu Text), wywołaj content.someKey.value, aby uzyskać właściwy łańcuch znaków.

Jeśli Twoja aplikacja już istnieje, możesz użyć Intlayer Compiler w połączeniu z poleceniem extract, aby przekonwertować tysiące komponentów w jedną sekundę.

(Opcjonalny) Krok 5: Zmiana lokalizacji aplikacji

Aby zmienić lokalizację z poziomu komponentów, możesz użyć metody setLocale hooka useLocale:

import { type FC } from "react";
import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
import { getLocaleName } from "intlayer";
import { useLocale } from "react-intlayer";

export const LocaleSwitcher: FC = () => {
  const { setLocale, availableLocales } = useLocale();

  return (
    <View style={styles.container}>
      {availableLocales.map((locale) => (
        <TouchableOpacity
          key={locale}
          style={styles.button}
          onPress={() => setLocale(locale)}
        >
          <Text style={styles.text}>{getLocaleName(locale)}</Text>
        </TouchableOpacity>
      ))}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flexDirection: "row",
    justifyContent: "center",
    alignItems: "center",
    gap: 8,
  },
  button: {
    paddingVertical: 6,
    paddingHorizontal: 12,
    borderRadius: 6,
    backgroundColor: "#ddd",
  },
  text: {
    fontSize: 14,
    fontWeight: "500",
    color: "#333",
  },
});

To powoduje ponowne renderowanie wszystkich komponentów korzystających z zawartości Intlayer, teraz wyświetlając tłumaczenia dla nowej lokalizacji.

Zobacz useLocale docs po więcej szczegółów.

Konfiguracja TypeScript (jeśli używasz TypeScript)

Intlayer generuje definicje typów w ukrytym folderze (domyślnie .intlayer), aby poprawić autouzupełnianie i wykrywać błędy tłumaczeń:

// tsconfig.json{  // ... twoja istniejąca konfiguracja TS  "include": [    "src", // twój kod źródłowy    ".intlayer/types/**/*.ts", // <-- upewnij się, że uwzględnione są automatycznie generowane typy    // ... wszystko inne, co już uwzględniasz  ],}

To umożliwia funkcje takie jak:

• Autouzupełnianie dla kluczy słownika.
• Sprawdzanie typów, które ostrzega, jeśli odwołujesz się do nieistniejącego klucza lub typ jest niezgodny.

Konfiguracja Git

Aby uniknąć zatwierdzania automatycznie generowanych plików przez Intlayer, dodaj następujące wpisy do swojego .gitignore:

#  Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby poprawić swoje doświadczenie deweloperskie z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z Marketplace VS Code

To rozszerzenie oferuje:

• Autouzupełnianie dla kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podglądy w linii przetłumaczonej zawartości.
• Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

Aby uzyskać więcej informacji o korzystaniu z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer VS Code.

Idź dalej

• Edytor wizualny: Użyj Intlayer Visual Editor do wizualnego zarządzania tłumaczeniami.
• Integracja z CMS: Możesz również zewnętrznie przechowywać i pobierać zawartość swojego słownika z CMS.
• Polecenia CLI: Poznaj Intlayer CLI do zadań takich jak wyodrębnianie tłumaczeń lub sprawdzanie brakujących kluczy.

Ciesz się tworzeniem swoich aplikacji React Native z pełnym wsparciem i18n dzięki Intlayer!

Debugowanie

React Native może być mniej stabilny niż React Web, dlatego zwróć szczególną uwagę na zgodność wersji.

Intlayer jest przede wszystkim skierowany do Web Intl API; na React Native musisz dołączyć odpowiednie polyfille.

Lista kontrolna:

• Używaj najnowszych wersji intlayer, react-intlayer oraz react-native-intlayer.
• Włącz polyfill Intlayer.
• Jeśli używasz getLocaleName lub innych narzędzi opartych na API Intl, zaimportuj te polyfille wcześnie (na przykład w index.js lub App.tsx):

import "intl";import "@formatjs/intl-getcanonicallocales/polyfill";import "@formatjs/intl-locale/polyfill";import "@formatjs/intl-pluralrules/polyfill";import "@formatjs/intl-displaynames/polyfill";import "@formatjs/intl-listformat/polyfill";import "@formatjs/intl-numberformat/polyfill";import "@formatjs/intl-relativetimeformat/polyfill";import "@formatjs/intl-datetimeformat/polyfill";

• Sprawdź konfigurację Metro (aliasy resolvera, wtyczki assetów, ścieżki w tsconfig), jeśli moduły nie mogą zostać rozwiązane.