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

Spis treści

Dlaczego Intlayer zamiast alternatyw?

W porównaniu do głównych rozwiązań, takich jak react-native-localize czy i18next, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

1. 1

   Zainstaluj zależności

   Zobacz Szablon aplikacji w GitHub.

   Z projektu React Native zainstaluj następujące pakiety:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npx intlayer init --interactive
   

   Flaga --interactive jest opcjonalna. Użyj intlayer-cli init, jeśli jesteś agentem AI.

   To polecenie wykryje Twoje środowisko i zainstaluje wymagane pakiety. Na przykład:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install intlayer react-native-intlayer
   

   Pakiety

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

   • react-native-intlayer
     Integracja z React Native, która dostarcza dostawców kontekstu oraz hooki React do pobierania i przełączania lokalizacji, polyfille dla React Native oraz wtyczkę Metro do integracji Intlayer z bundlerem React Native. Reeksportuje wszystko z react-intlayer, więc w aplikacji React Native potrzebny jest tylko ten jeden pakiet.

2. 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:

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   /**
    * 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.
3. 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:

   metro.config.js

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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

4. 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.

   Zawsze importuj z react-native-intlayer. Jego IntlayerProvider zawiera polyfille dla web API używanego przez Intlayer, a pakiet reeksportuje wszystkie hooki i narzędzia z react-intlayer.

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

   app/_layout.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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;
   

5. 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.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • itd.

   Expo Router (web): trzymaj pliki .content.* poza katalogiem app/. Expo Router traktuje każdy plik JavaScript/TypeScript wewnątrz app/ jako ścieżkę (route). W sieci web odkrywanie ścieżek skanuje system plików bezpośrednio i nie honoruje resolver.blockList z Metro, więc współistniejący plik *.content.ts jest rejestrowany jako ścieżka. Plik taki jak app/(tabs)/_layout.content.ts jest nawet parsowany jako układ (layout - część .content jest czytana jako przyrostek platformy), co koliduje z prawdziwym _layout.tsx i wyrzuca błąd:

   plaintext

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.
   

   Umieść swoje deklaracje w katalogu poza app/ (na przykład content/ lub src/content/). Intlayer odkrywa pliki .content.* w dowolnym miejscu w projekcie, a słowniki są odnoszone przez ich key, więc nie są potrzebne żadne zmiany importów. W aplikacjach natywnych nie jest to wymagane (blockList z Metro już je ukrywa), ale używanie katalogu innego niż app/ zapewnia działanie na obu platformach.

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

   src/app.content.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   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.

6. 6

   Użyj Intlayer w swoich komponentach

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

   Przykład

   app/(tabs)/index.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-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ę.

7. 7

   Zmiana lokalizacji aplikacji

   Opcjonalne

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

   src/components/LocaleSwitcher.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-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 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.

Często Zadawane Pytania