Terjemahkan situs web Vite dan React Anda menggunakan Intlayer | Internasionalisasi (i18n)

Daftar Isi

Apa itu Intlayer?

Intlayer adalah perpustakaan internasionalisasi (i18n) open-source yang inovatif, dirancang untuk menyederhanakan dukungan multibahasa dalam aplikasi web modern.

Dengan Intlayer, Anda dapat:

• Mengelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
• Melokalkan metadata, rute, dan konten secara dinamis.
• Memastikan dukungan TypeScript dengan tipe yang dihasilkan secara otomatis, meningkatkan autocompletion dan deteksi kesalahan.
• Memanfaatkan fitur canggih, seperti deteksi dan pergantian locale secara dinamis.

Panduan Langkah demi Langkah untuk Mengatur Intlayer dalam Aplikasi Vite dan React

Lihat Application Template di GitHub.

Langkah 1: Instalasi Dependencies

Instal paket yang diperlukan menggunakan npm:

npm install intlayer react-intlayernpm install vite-intlayer --save-dev

• intlayer

• intlayer

  Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpile, dan perintah CLI.

• react-intlayer Paket yang mengintegrasikan Intlayer dengan aplikasi React. Paket ini menyediakan context providers dan hooks untuk internasionalisasi React.

• vite-intlayer Termasuk plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi locale yang dipilih pengguna, mengelola cookie, dan menangani pengalihan URL.

Langkah 2: Konfigurasi proyek Anda

Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Bahasa lain yang Anda gunakan    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Melalui file konfigurasi ini, Anda dapat mengatur URL yang dilokalkan, pengalihan middleware, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan lainnya. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.

Langkah 3: Integrasikan Intlayer dalam Konfigurasi Vite Anda

Tambahkan plugin intlayer ke dalam konfigurasi Anda.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer()],});

Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Plugin ini memastikan pembuatan file deklarasi konten dan memantau file tersebut dalam mode pengembangan. Plugin ini juga mendefinisikan variabel lingkungan Intlayer dalam aplikasi Vite. Selain itu, plugin ini menyediakan alias untuk mengoptimalkan performa.

Langkah 4: Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    viteLogo: t({      en: "Vite logo",      fr: "Logo Vite",      es: "Logo Vite",    }),    reactLogo: t({      en: "React logo",      fr: "Logo React",      es: "Logo React",    }),    title: "Vite + React",    count: t({      en: "count is ",      fr: "le compte est ",      es: "el recuento es ",    }),    edit: t<ReactNode>({      en: (        <>          Edit <code>src/App.tsx</code> dan simpan untuk menguji HMR        </>      ),      fr: (        <>          Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR        </>      ),      es: (        <>          Edita <code>src/App.tsx</code> y guarda para probar HMR        </>      ),    }),    readTheDocs: t({      en: "Klik pada logo Vite dan React untuk mempelajari lebih lanjut",      fr: "Cliquez sur les logos Vite et React pour en savoir plus",      es: "Haga clic en los logotipos de Vite y React para obtener más información",    }),  },} satisfies Dictionary;export default appContent;

Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama sudah termasuk ke dalam direktori contentDir (secara default, ./src). Dan sesuai dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

Jika file konten Anda menyertakan kode TSX, Anda harus mempertimbangkan untuk mengimpor import React from "react"; dalam file konten Anda.

Langkah 5: Gunakan Intlayer dalam Kode Anda

Akses kamus konten Anda di seluruh aplikasi Anda:

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => {  const [count, setCount] = useState(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} className="logo" alt={content.viteLogo.value} />        </a>        <a href="https://react.dev" target="_blank">          <img            src={reactLogo}            className="logo react"            alt={content.reactLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div className="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count}          {count}        </button>        <p>{content.edit}</p>      </div>      <p className="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

Jika Anda ingin menggunakan konten Anda dalam atribut string, seperti alt, title, href, aria-label, dll., Anda harus memanggil nilai fungsi tersebut, seperti:

<img src={content.image.src.value} alt={content.image.value} />

Untuk mempelajari lebih lanjut tentang hook useIntlayer, lihat dokumentasi.

(Opsional) Langkah 6: Ubah bahasa konten Anda

Untuk mengubah bahasa konten Anda, Anda dapat menggunakan fungsi setLocale yang disediakan oleh hook useLocale. Fungsi ini memungkinkan Anda untuk mengatur locale aplikasi dan memperbarui konten sesuai dengan locale tersebut.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Ubah Bahasa ke Bahasa Inggris    </button>  );};

Untuk mempelajari lebih lanjut tentang hook useLocale, lihat dokumentasi.

(Opsional) Langkah 7: Tambahkan Routing yang Dilokalkan ke aplikasi Anda

Tujuan dari langkah ini adalah untuk membuat rute unik untuk setiap bahasa. Ini berguna untuk SEO dan URL yang ramah SEO. Contoh:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

Secara default, rute tidak diberi awalan untuk locale default. Jika Anda ingin memberi awalan pada locale default, Anda dapat mengatur opsi middleware.prefixDefault ke true dalam konfigurasi Anda. Lihat dokumentasi konfigurasi untuk informasi lebih lanjut.

Untuk menambahkan routing yang dilokalkan ke aplikasi Anda, Anda dapat membuat komponen LocaleRouter yang membungkus rute aplikasi Anda dan menangani routing berbasis locale. Berikut adalah contoh menggunakan React Router:

import { localeMap } from "intlayer"; // Fungsi utilitas dan tipe dari 'intlayer'import type { FC, PropsWithChildren } from "react"; // Tipe React untuk komponen fungsional dan propsimport { IntlayerProvider } from "react-intlayer"; // Provider untuk konteks internasionalisasiimport { BrowserRouter, Route, Routes } from "react-router-dom"; // Komponen router untuk mengelola navigasi/** * Komponen router yang mengatur rute spesifik berdasarkan locale. * Menggunakan React Router untuk mengelola navigasi dan merender komponen yang dilokalkan. */export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (  <BrowserRouter>    <Routes>      {localeMap(({ locale, urlPrefix }) => (        <Route          // Pola rute untuk menangkap locale (misal: /en/, /fr/) dan mencocokkan semua path berikutnya          path={`${urlPrefix}/*`}          key={locale}          element={            <IntlayerProvider locale={locale}>{children}</IntlayerProvider>          } // Membungkus children dengan pengelolaan locale        />      ))}    </Routes>  </BrowserRouter>);

Catatan: Jika Anda menggunakan routing.mode: 'no-prefix' | 'search-params', Anda mungkin tidak perlu menggunakan fungsi localeMap.

Kemudian, Anda dapat menggunakan komponen LocaleRouter dalam aplikasi Anda:

import { LocaleRouter } from "./components/LocaleRouter";import type { FC } from "react";// ... Komponen AppContent Andaconst App: FC = () => (  <LocaleRouter>    <AppContent />  </LocaleRouter>);

Secara paralel, Anda juga dapat menggunakan intlayerProxy untuk menambahkan routing sisi server ke aplikasi Anda. Plugin ini akan secara otomatis mendeteksi locale saat ini berdasarkan URL dan mengatur cookie locale yang sesuai. Jika tidak ada locale yang ditentukan, plugin akan menentukan locale yang paling sesuai berdasarkan preferensi bahasa browser pengguna. Jika tidak ada locale yang terdeteksi, maka akan mengarahkan ulang ke locale default.

Perlu dicatat bahwa untuk menggunakan intlayerProxy dalam produksi, Anda perlu memindahkan paket vite-intlayer dari devDependencies ke dependencies.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerProxy } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerProxy()],});

(Opsional) Langkah 8: Ubah URL saat locale berubah

Untuk mengubah URL saat locale berubah, Anda dapat menggunakan properti onLocaleChange yang disediakan oleh hook useLocale. Secara paralel, Anda dapat menggunakan hook useLocation dan useNavigate dari react-router-dom untuk memperbarui path URL.

import { useLocation, useNavigate } from "react-router-dom";import {  Locales,  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,} from "intlayer";import { useLocale } from "react-intlayer";import { type FC } from "react";const LocaleSwitcher: FC = () => {  const { pathname, search } = useLocation(); // Dapatkan path URL saat ini. Contoh: /fr/about?foo=bar  const navigate = useNavigate();  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (locale) => {      // Bangun URL dengan locale yang diperbarui      // Contoh: /es/about?foo=bar      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);      // Perbarui path URL      navigate(pathWithLocale);    },  });  return (    <div>      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>      <div id="localePopover" popover="auto">        {availableLocales.map((localeItem) => (          <a            href={getLocalizedUrl(location.pathname, localeItem)}            hrefLang={localeItem}            aria-current={locale === localeItem ? "page" : undefined}            onClick={(e) => {              e.preventDefault();              setLocale(localeItem);            }}            key={localeItem}          >            <span>              {/* Lokal - misal FR */}              {localeItem}            </span>            <span>              {/* Bahasa dalam Lokal sendiri - misal Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Bahasa dalam Lokal saat ini - misal Francés dengan lokal saat ini diset ke Locales.SPANISH */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* Bahasa dalam Bahasa Inggris - misalnya French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </a>        ))}      </div>    </div>  );};

Referensi dokumentasi:

• useLocale hook
• getLocaleName hook
• getLocalizedUrl hook
• getHTMLTextDir hook
• hrefLang attribute
• lang attribute
• dir attribute`
• aria-current attribute`

Berikut adalah Langkah 9 yang diperbarui dengan penjelasan tambahan dan contoh kode yang disempurnakan:

(Opsional) Langkah 9: Mengganti Atribut Bahasa dan Arah pada HTML

Ketika aplikasi Anda mendukung banyak bahasa, sangat penting untuk memperbarui atribut lang dan dir pada tag <html> agar sesuai dengan locale saat ini. Melakukan hal ini memastikan:

• Aksesibilitas: Pembaca layar dan teknologi bantu bergantung pada atribut lang yang benar untuk mengucapkan dan menginterpretasikan konten dengan akurat.
• Rendering Teks: Atribut dir (arah) memastikan teks ditampilkan dalam urutan yang tepat (misalnya, kiri-ke-kanan untuk bahasa Inggris, kanan-ke-kiri untuk bahasa Arab atau Ibrani), yang sangat penting untuk keterbacaan.
• SEO: Mesin pencari menggunakan atribut lang untuk menentukan bahasa halaman Anda, membantu menyajikan konten lokal yang tepat dalam hasil pencarian.

Dengan memperbarui atribut ini secara dinamis saat locale berubah, Anda menjamin pengalaman yang konsisten dan dapat diakses bagi pengguna di semua bahasa yang didukung.

Mengimplementasikan Hook

Buat hook kustom untuk mengelola atribut HTML. Hook ini mendengarkan perubahan locale dan memperbarui atribut sesuai:

import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";/** * Memperbarui atribut `lang` dan `dir` elemen HTML <html> berdasarkan locale saat ini. * - `lang`: Memberitahu browser dan mesin pencari tentang bahasa halaman. * - `dir`: Memastikan urutan bacaan yang benar (misalnya, 'ltr' untuk Bahasa Inggris, 'rtl' untuk Bahasa Arab). * * Pembaruan dinamis ini penting untuk rendering teks yang tepat, aksesibilitas, dan SEO. */export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    // Perbarui atribut bahasa ke locale saat ini.    document.documentElement.lang = locale;    // Atur arah teks berdasarkan locale saat ini.    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

Menggunakan Hook di Aplikasi Anda

Integrasikan hook ini ke dalam komponen utama Anda sehingga atribut HTML akan diperbarui setiap kali locale berubah:

import type { FC } from "react";import { IntlayerProvider, useIntlayer } from "react-intlayer";import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";import "./App.css";const AppContent: FC = () => {  // Terapkan hook untuk memperbarui atribut lang dan dir pada tag <html> berdasarkan locale.  useI18nHTMLAttributes();  // ... Sisa komponen Anda};const App: FC = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

Dengan menerapkan perubahan ini, aplikasi Anda akan:

• Memastikan atribut bahasa (lang) mencerminkan locale saat ini dengan benar, yang penting untuk SEO dan perilaku browser.
• Menyesuaikan arah teks (dir) sesuai dengan locale, meningkatkan keterbacaan dan kegunaan untuk bahasa dengan urutan baca yang berbeda.
• Memberikan pengalaman yang lebih aksesibel, karena teknologi bantu bergantung pada atribut ini agar berfungsi secara optimal.

(Opsional) Langkah 10: Membuat Komponen Link yang Dilokalkan

Untuk memastikan navigasi aplikasi Anda menghormati locale saat ini, Anda dapat membuat komponen Link kustom. Komponen ini secara otomatis menambahkan prefix bahasa saat ini pada URL internal, sehingga. Misalnya, ketika pengguna berbahasa Prancis mengklik tautan ke halaman "About", mereka akan diarahkan ke /fr/about bukan /about.

Perilaku ini berguna untuk beberapa alasan:

• SEO dan Pengalaman Pengguna: URL yang dilokalisasi membantu mesin pencari mengindeks halaman spesifik bahasa dengan benar dan menyediakan konten kepada pengguna dalam bahasa pilihan mereka.
• Konsistensi: Dengan menggunakan tautan yang dilokalisasi di seluruh aplikasi Anda, Anda menjamin navigasi tetap dalam locale saat ini, mencegah perubahan bahasa yang tidak diinginkan.
• Maintainability: Memusatkan logika lokalisasi dalam satu komponen menyederhanakan pengelolaan URL, sehingga codebase Anda lebih mudah dipelihara dan dikembangkan seiring pertumbuhan aplikasi Anda.

Berikut adalah implementasi komponen Link yang dilokalisasi dalam TypeScript:

import { getLocalizedUrl } from "intlayer";import {  forwardRef,  type DetailedHTMLProps,  type AnchorHTMLAttributes,} from "react";import { useLocale } from "react-intlayer";export interface LinkProps  extends DetailedHTMLProps<    AnchorHTMLAttributes<HTMLAnchorElement>,    HTMLAnchorElement  > {}/** * Fungsi utilitas untuk memeriksa apakah URL yang diberikan bersifat eksternal. * Jika URL dimulai dengan http:// atau https://, maka dianggap eksternal. */export const checkIsExternalLink = (href?: string): boolean =>  /^https?:\/\//.test(href ?? "");/** * Komponen Link kustom yang menyesuaikan atribut href berdasarkan locale saat ini. * Untuk tautan internal, menggunakan `getLocalizedUrl` untuk menambahkan prefix locale pada URL (misalnya, /fr/about). * Ini memastikan navigasi tetap dalam konteks locale yang sama. */export const Link = forwardRef<HTMLAnchorElement, LinkProps>(  ({ href, children, ...props }, ref) => {    const { locale } = useLocale();    const isExternalLink = checkIsExternalLink(href);    // Jika tautan bersifat internal dan href valid disediakan, dapatkan URL yang sudah dilokalkan.    const hrefI18n =      href && !isExternalLink ? getLocalizedUrl(href, locale) : href;    return (      <a href={hrefI18n} ref={ref} {...props}>        {children}      </a>    );  });Link.displayName = "Link";

Cara Kerjanya

• Mendeteksi Tautan Eksternal:
  Fungsi pembantu checkIsExternalLink menentukan apakah sebuah URL adalah eksternal. Tautan eksternal dibiarkan tidak berubah karena tidak memerlukan lokalisasi.

• Mengambil Locale Saat Ini:
  Hook useLocale menyediakan locale saat ini (misalnya, fr untuk bahasa Perancis).

• Melokalisasi URL:
  Untuk tautan internal (yaitu, bukan eksternal), getLocalizedUrl digunakan untuk secara otomatis menambahkan prefix locale pada URL. Ini berarti jika pengguna Anda menggunakan bahasa Perancis, memberikan /about sebagai href akan mengubahnya menjadi /fr/about.

• Mengembalikan Link:
  Komponen mengembalikan elemen <a> dengan URL yang sudah dilokalisasi, memastikan navigasi konsisten dengan locale.

Dengan mengintegrasikan komponen Link ini di seluruh aplikasi Anda, Anda mempertahankan pengalaman pengguna yang koheren dan sadar bahasa sekaligus mendapatkan manfaat dari peningkatan SEO dan kegunaan.

Konfigurasi TypeScript

Intlayer menggunakan module augmentation untuk mendapatkan manfaat dari TypeScript dan membuat codebase Anda lebih kuat.

Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis.

{  // ... Konfigurasi TypeScript Anda yang sudah ada  "include": [    // ... Konfigurasi TypeScript Anda yang sudah ada    ".intlayer/**/*.ts", // Sertakan tipe yang dihasilkan secara otomatis  ],}

Konfigurasi Git

Disarankan untuk mengabaikan file-file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda untuk menghindari meng-commit file tersebut ke repositori Git Anda.

Untuk melakukan ini, Anda dapat menambahkan instruksi berikut ke file .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 yang diterjemahkan.
• 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

Untuk melangkah lebih jauh, Anda dapat mengimplementasikan editor visual atau mengeksternalisasi konten Anda menggunakan CMS.