Terjemahkan website backend Elysia Anda menggunakan Intlayer | Internationalization (i18n)

elysia-intlayer adalah plugin internationalization (i18n) yang powerful untuk aplikasi Elysia, dirancang untuk membuat layanan backend Anda dapat diakses secara global dengan menyediakan respons yang terlokalisasi berdasarkan preferensi klien.

Lihat implementasi package di GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Kasus Penggunaan Praktis

• Menampilkan Error Backend dalam Bahasa Pengguna: Ketika terjadi kesalahan, menampilkan pesan dalam bahasa asli pengguna meningkatkan pemahaman dan mengurangi frustrasi. Ini sangat berguna untuk pesan error dinamis yang mungkin ditampilkan dalam komponen front-end seperti toasts atau modals.
• Mengambil Konten Multibahasa: Untuk aplikasi yang menarik konten dari database, internasionalisasi memastikan bahwa Anda dapat menyajikan konten ini dalam berbagai bahasa. Ini sangat penting untuk platform seperti situs e-commerce atau sistem manajemen konten yang perlu menampilkan deskripsi produk, artikel, dan konten lainnya dalam bahasa yang disukai pengguna.
• Mengirim Email Multibahasa: Baik itu email transaksional, kampanye pemasaran, atau notifikasi, mengirim email dalam bahasa penerima dapat meningkatkan engagement dan efektivitas secara signifikan.
• Notifikasi Push Multibahasa: Untuk aplikasi mobile, mengirim notifikasi push dalam bahasa pilihan pengguna dapat meningkatkan interaksi dan retensi. Sentuhan personal ini dapat membuat notifikasi terasa lebih relevan dan dapat ditindaklanjuti.
• Komunikasi Lainnya: Segala bentuk komunikasi dari backend, seperti pesan SMS, alert sistem, atau pembaruan antarmuka pengguna, mendapat manfaat dari penggunaan bahasa pengguna, memastikan kejelasan dan meningkatkan pengalaman pengguna secara keseluruhan.

Dengan menginternasionalisasi backend, aplikasi Anda tidak hanya menghormati perbedaan budaya tetapi juga selaras lebih baik dengan kebutuhan pasar global, menjadikannya langkah kunci dalam menskalakan layanan Anda di seluruh dunia.

Memulai

Lihat Template Aplikasi di GitHub.

Instalasi

Untuk mulai menggunakan elysia-intlayer, instal paket menggunakan npm:

npx intlayer init --interactive

flag --interactive bersifat opsional. Gunakan intlayer-cli init jika Anda adalah agen AI.

Perintah ini akan mendeteksi lingkungan Anda dan menginstal paket yang diperlukan. Contohnya:

npm install intlayer elysia-intlayer

Elysia menargetkan runtime Bun. elysia-intlayer mengandalkan AsyncLocalStorage (alih-alih library cls-hooked yang dipakai plugin Intlayer berbasis Node) justru karena Bun tidak mengimplementasikan async_hooks.createHook.

Penyiapan

Konfigurasikan pengaturan internasionalisasi dengan membuat intlayer.config.ts di root proyek Anda:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * Locale default yang dipakai sebagai fallback jika locale yang diminta tidak ditemukan.
     */
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Deklarasikan Konten Anda

Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:

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

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      id: "Contoh konten yang dikembalikan dalam bahasa Indonesia",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda selama disertakan dalam direktori contentDir (secara default, ./src). Dan cocok dengan ekstensi file deklarasi konten (secara default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.

Pengaturan Aplikasi Elysia

Atur aplikasi Elysia Anda untuk menggunakan elysia-intlayer:

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia()
  // Muat plugin internasionalisasi
  .use(intlayer())
  // Routes
  .get("/", ({ intlayer }) => ({
    // Locale yang digunakan untuk permintaan ini, `Accept-Language` dinegosiasikan atau dibaca dari penyimpanan
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      id: "Halo",
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Plugin mendaftarkan context-nya melalui derive global, yang oleh Elysia diberi tipe Partial<{ intlayer: IntlayerContext }>. Nilainya selalu ada saat runtime untuk route yang didaftarkan setelah .use(intlayer()), jadi gunakan non-null assertion (intlayer!.locale) — atau optional chaining — agar TypeScript pada mode strict puas.

Context route menyediakan:

Helper yang sama juga diekspor secara standalone. Mereka menyelesaikan request saat ini melalui AsyncLocalStorage, sehingga Anda bisa memanggilnya tanpa melakukan destructuring pada context:

import { Elysia } from "elysia";
import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
import dictionaryExample from "./index.content";

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      id: "Contoh konten yang dikembalikan dalam bahasa Indonesia",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

Konteks request dilepaskan setelah response dipetakan, sehingga helper mandiri tidak pernah diselesaikan terhadap request yang sudah berakhir. Ketika dipanggil di luar request yang ditangani plugin, keduanya beralih ke locale default yang dikonfigurasi.

Menjalankan Aplikasi Anda

Tambahkan script Intlayer ke package.json Anda. intlayer build mengompilasi deklarasi konten Anda ke direktori .intlayer dan menghasilkan tipe TypeScript:

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Lalu jalankan server:

bun run dev

Uji negosiasi locale dengan Accept-Language:

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

intlayer build tidak wajib dijalankan sebelum bun run src/index.ts: plugin juga menyiapkan dictionary saat aplikasi Elysia melakukan boot. Menjalankannya lebih dulu membuat tipe yang dihasilkan tetap sinkron untuk editor Anda dan menghindari biaya build pada request pertama.

Kompatibilitas

elysia-intlayer sepenuhnya kompatibel dengan:

• react-intlayer untuk aplikasi React
• next-intlayer untuk aplikasi Next.js
• vite-intlayer untuk aplikasi Vite

Ini juga bekerja dengan mulus dengan solusi internasionalisasi apa pun di berbagai lingkungan, termasuk browser dan permintaan API.

Secara default, plugin menyelesaikan locale dengan urutan berikut:

1. Cookie INTLAYER_LOCALE.
2. Header x-intlayer-locale.
3. Negosiasi header Accept-Language.

Anda dapat menyesuaikan cookie dan header yang dipakai untuk deteksi locale:

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

const config: IntlayerConfig = {
  // ... Opsi konfigurasi lainnya
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Untuk informasi lebih lanjut tentang konfigurasi dan topik lanjutan, kunjungi dokumentasi kami.

Konfigurasi TypeScript

elysia-intlayer memanfaatkan kemampuan robust TypeScript untuk meningkatkan proses internasionalisasi. Pengetikan statis TypeScript memastikan bahwa setiap kunci terjemahan diperhitungkan, mengurangi risiko terjemahan yang hilang dan meningkatkan maintainability.

Pastikan tipe yang dihasilkan secara otomatis (secara default di ./types/intlayer.d.ts) disertakan dalam file tsconfig.json Anda.

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

Ekstensi VS Code

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

Instal dari VS Code Marketplace

Ekstensi ini menyediakan:

• Autocompletion untuk kunci terjemahan.
• Deteksi kesalahan real-time 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, lihat dokumentasi Intlayer VS Code Extension.

Konfigurasi Git

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

Untuk melakukan ini, Anda dapat menambahkan instruksi berikut ke file .gitignore Anda:

# Abaikan file yang dihasilkan oleh Intlayer
.intlayer