Terjemahkan situs aplikasi mobile Lynx dan React Anda menggunakan Intlayer | Internasionalisasi (i18n)

Lihat Application Template di GitHub.

Apa itu Intlayer?

Intlayer adalah perpustakaan internasionalisasi (i18n) open-source yang inovatif yang mempermudah dukungan multibahasa dalam aplikasi modern. Ini bekerja di banyak lingkungan JavaScript/TypeScript, termasuk Lynx (melalui paket react-intlayer).

Dengan Intlayer, Anda dapat:

• Kelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
• Pastikan dukungan TypeScript dengan tipe yang dihasilkan secara otomatis.
• Lokalisisasi konten secara dinamis, termasuk string UI (dan di React untuk web, juga dapat melokalisasi metadata HTML, dll.).
• Manfaatkan fitur canggih, seperti deteksi dan pergantian locale secara dinamis.

Langkah 1: Instalasi Dependensi

Dari proyek Lynx Anda, instal paket-paket berikut:

npm install intlayer react-intlayer lynx-intlayernpx intlayer init

Paket

• intlayer

• intlayer
  Toolkit inti i18n untuk konfigurasi, konten kamus, pembuatan tipe, dan perintah CLI.

• react-intlayer
  Integrasi React yang menyediakan context providers dan React hooks yang akan Anda gunakan di Lynx untuk mendapatkan dan mengganti locale.

• lynx-intlayer
  Integrasi Lynx yang menyediakan plugin untuk mengintegrasikan Intlayer dengan bundler Lynx.

Langkah 2: Buat Konfigurasi Intlayer

Di root proyek Anda (atau di mana saja yang nyaman), buat file konfigurasi Intlayer. Contohnya bisa seperti ini:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // ... Tambahkan locale lain yang Anda butuhkan
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Dalam konfigurasi ini, Anda dapat:

• Mengonfigurasi daftar locale yang didukung.
• Menetapkan locale default.
• Nanti, Anda dapat menambahkan opsi yang lebih canggih (misalnya, log, direktori konten khusus, dll.).
• Lihat dokumentasi konfigurasi Intlayer untuk informasi lebih lanjut.

Langkah 3: Tambahkan plugin Intlayer ke bundler Lynx

Untuk menggunakan Intlayer dengan Lynx, Anda perlu menambahkan plugin ke file lynx.config.ts Anda:

import { defineConfig } from "@lynx-js/rspeedy";import { pluginIntlayerLynx } from "lynx-intlayer/plugin";export default defineConfig({  plugins: [    // ... plugin lain    pluginIntlayerLynx(),  ],});

Langkah 4: Tambahkan provider Intlayer

Untuk menjaga sinkronisasi bahasa pengguna di seluruh aplikasi Anda, Anda perlu membungkus komponen root Anda dengan komponen IntlayerProvider dari react-intlayer.

Selain itu, Anda perlu menambahkan file fungsi intlayerPolyfill untuk memastikan Intlayer dapat bekerja dengan baik.

import { root } from "@lynx-js/react";import { App } from "./App.js";import { IntlayerProvider } from "react-intlayer";import { intlayerPolyfill } from "lynx-intlayer";intlayerPolyfill();root.render(  <IntlayerProvider>    <App />  </IntlayerProvider>);if (import.meta.webpackHot) {  import.meta.webpackHot.accept();}

Langkah 5: Deklarasikan Konten Anda

Buat file deklarasi konten di mana saja dalam proyek Anda (biasanya di dalam src/), menggunakan salah satu format ekstensi yang didukung oleh Intlayer:

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

Contoh:

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

const appContent = {
  key: "app",
  content: {
    title: "React",
    subtitle: t({
      en: "on Lynx",
      fr: "sur Lynx",
      es: "en Lynx",
    }),
    description: t({
      en: "Tap the logo and have fun!",
      fr: "Appuyez sur le logo et amusez-vous!",
      es: "¡Toca el logo y diviértete!",
    }),
    hint: [
      t({
        en: "Edit",
        fr: "Modifier",
        es: "Editar",
      }),
      " src/App.tsx ",
      t({
        en: "untuk melihat pembaruan!",
        fr: "pour voir les mises à jour!",
        es: "para ver actualizaciones!",
      }),
    ],
  },
} satisfies Dictionary;

export default appContent;

Untuk detail tentang deklarasi konten, lihat dokumentasi konten Intlayer.

Langkah 4: Gunakan Intlayer di Komponen Anda

Gunakan hook useIntlayer di komponen anak untuk mendapatkan konten yang sudah dilokalisasi.

import { useCallback, useState } from "@lynx-js/react";import { useIntlayer } from "react-intlayer";import "./App.css";import arrow from "./assets/arrow.png";import lynxLogo from "./assets/lynx-logo.png";import reactLynxLogo from "./assets/react-logo.png";import { LocaleSwitcher } from "./components/LocaleSwitcher.jsx";export const App = () => {  const [alterLogo, setAlterLogo] = useState(false);  const { title, subtitle, description, hint } = useIntlayer("app");  const onTap = useCallback(() => {    "background only";    setAlterLogo(!alterLogo);  }, [alterLogo]);  return (    <view>      <view className="Background" />      <view className="App">        <view className="Banner">          <view className="Logo" bindtap={onTap}>            {alterLogo ? (              <image src={reactLynxLogo} className="Logo--react" />            ) : (              <image src={lynxLogo} className="Logo--lynx" />            )}          </view>          <text className="Title">{title}</text>          <text className="Subtitle">{subtitle}</text>        </view>        <view className="Content">          <image src={arrow} className="Arrow" />          <text className="Description">{description}</text>          <text className="Hint">            {hint[0]}            <text style={{ fontStyle: "italic" }}>{hint[1]}</text>            {hint[2]}          </text>        </view>        <LocaleSwitcher />        <view style={{ flex: 1 }}></view>      </view>    </view>  );};

Saat menggunakan content.someKey dalam props berbasis string (misalnya, title pada tombol atau children pada komponen Text), panggil content.someKey.value untuk mendapatkan string yang sebenarnya.

(Opsional) Langkah 5: Ubah Locale Aplikasi

Untuk mengganti locale dari dalam komponen Anda, Anda dapat menggunakan metode setLocale dari hook useLocale:

import { type FC } from "react";import { getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale, availableLocales, locale } = useLocale();  return (    <view      style={{        display: "flex",        flexDirection: "row",        justifyContent: "center",        alignItems: "center",        gap: 10,      }}    >      {availableLocales.map((localeEl) => (        <text          key={localeEl}          style={{            color: localeEl === locale ? "#fff" : "#888",            fontSize: "12px",          }}          bindtap={() => setLocale(localeEl)}        >          {getLocaleName(localeEl)}        </text>      ))}    </view>  );};

Ini memicu re-render semua komponen yang menggunakan konten Intlayer, yang sekarang menampilkan terjemahan untuk locale baru.

Lihat dokumentasi useLocale untuk detail lebih lanjut.

Konfigurasi TypeScript (jika Anda menggunakan TypeScript)

Intlayer menghasilkan definisi tipe dalam folder tersembunyi (secara default .intlayer) untuk meningkatkan autocompletion dan menangkap kesalahan terjemahan:

// tsconfig.json{  // ... konfigurasi TS Anda yang sudah ada  "include": [    "src", // kode sumber Anda    ".intlayer/types/**/*.ts", // <-- pastikan tipe yang dihasilkan otomatis disertakan    // ... apapun yang sudah Anda sertakan  ],}

Ini yang memungkinkan fitur seperti:

• Autocompletion untuk kunci kamus Anda.
• Pemeriksaan tipe yang memperingatkan jika Anda mengakses kunci yang tidak ada atau tipe yang tidak cocok.

Konfigurasi Git

Untuk menghindari commit file yang dihasilkan otomatis oleh Intlayer, tambahkan berikut ini ke .gitignore Anda:

#  Abaikan file yang dihasilkan oleh Intlayer.intlayer

Ekstensi VS Code

Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat menginstal Ekstensi VS Code Intlayer resmi.

Pasang dari VS Code Marketplace

Ekstensi ini menyediakan:

• Autocompletion untuk kunci terjemahan.
• Deteksi kesalahan waktu nyata untuk terjemahan yang hilang.
• Pratinjau inline dari konten terjemahan.
• Tindakan cepat untuk dengan mudah membuat dan memperbarui terjemahan.

Untuk detail lebih lanjut tentang cara menggunakan ekstensi ini, lihat dokumentasi Ekstensi VS Code Intlayer.

Melangkah Lebih Jauh

• Editor Visual: Gunakan Editor Visual Intlayer untuk mengelola terjemahan secara visual.
• Integrasi CMS: Anda juga dapat mengeksternalisasi dan mengambil konten kamus Anda dari sebuah CMS.
• Perintah CLI: Jelajahi Intlayer CLI untuk tugas seperti mengekstrak terjemahan atau memeriksa kunci yang hilang.