Dokumentasi: Fungsi t di express-intlayer

Fungsi t dalam paket express-intlayer adalah utilitas inti untuk menyediakan respons yang dilokalisasi dalam aplikasi Express Anda. Fungsi ini mempermudah internasionalisasi (i18n) dengan memilih konten secara dinamis berdasarkan bahasa yang dipilih pengguna.

Ikhtisar

Fungsi t digunakan untuk mendefinisikan dan mengambil terjemahan untuk satu set bahasa tertentu. Fungsi ini secara otomatis menentukan bahasa yang tepat untuk dikembalikan berdasarkan pengaturan permintaan klien, seperti header Accept-Language. Jika bahasa yang dipilih tidak tersedia, fungsi ini dengan mulus akan kembali ke locale default yang ditentukan dalam konfigurasi Anda.

Fitur Utama

• Lokalisasi Dinamis: Secara otomatis memilih terjemahan yang paling sesuai untuk klien.
• Fallback ke Locale Default: Kembali ke locale default jika bahasa pilihan klien tidak tersedia, memastikan kelangsungan pengalaman pengguna.
• Ringan dan Cepat: Dirancang untuk aplikasi dengan performa tinggi, memastikan overhead minimal.
• Dukungan Mode Ketat: Menerapkan kepatuhan ketat pada locale yang dideklarasikan untuk perilaku yang dapat diandalkan.

Tanda Tangan Fungsi

t(translations: Record<string, string>): string;

Parameter

• translations: Sebuah objek di mana kunci adalah kode locale (misalnya, en, fr, es-MX) dan nilainya adalah string terjemahan yang sesuai.

Mengembalikan

• Sebuah string yang mewakili konten dalam bahasa pilihan klien.

Memuat Handler Permintaan Internasionalisasi

Untuk memastikan bahwa fungsi internasionalisasi yang disediakan oleh express-intlayer bekerja dengan benar, Anda harus memuat middleware internasionalisasi di awal aplikasi Express Anda. Ini memungkinkan fungsi t dan memastikan penanganan yang tepat untuk deteksi locale dan terjemahan.

Tempatkan middleware app.use(intlayer()) sebelum rute apa pun dalam aplikasi Anda untuk memastikan bahwa semua rute mendapatkan manfaat dari internasionalisasi:

import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

// Memuat handler permintaan internasionalisasi
app.use(intlayer());

// Definisikan rute Anda setelah memuat middleware
app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
    })
  );
});

Mengapa Ini Diperlukan

• Deteksi Locale: Middleware intlayer memproses permintaan yang masuk untuk mendeteksi locale yang dipilih pengguna berdasarkan header, cookie, atau metode lain yang dikonfigurasi.
• Konteks Terjemahan: Menyiapkan konteks yang diperlukan agar fungsi t dapat beroperasi dengan benar, memastikan terjemahan dikembalikan dalam bahasa yang tepat.
• Pencegahan Error: Tanpa middleware ini, penggunaan fungsi t akan menyebabkan error saat runtime karena informasi locale yang diperlukan tidak tersedia.

Contoh Penggunaan

Contoh Dasar

Melayani konten yang dilokalkan dalam berbagai bahasa:

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

Permintaan Klien:

• Klien dengan Accept-Language: fr akan menerima Bienvenue!.
• Klien dengan Accept-Language: es akan menerima ¡Bienvenido!.
• Klien dengan Accept-Language: de akan menerima Welcome! (locale default).

Menangani Error

Berikan pesan error dalam berbagai bahasa:

javascript fileName="src/index.ts" codeFormat="typescript"
app.get("/error", (_req, res) => {
  res.status(500).send(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    })
  );
});

Menggunakan Varian Locale

Tentukan terjemahan untuk varian spesifik locale:

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

Topik Lanjutan

Mekanisme Fallback

Jika locale yang diinginkan tidak tersedia, fungsi t akan kembali menggunakan locale default yang didefinisikan dalam konfigurasi:

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

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Sebagai contoh:

• Jika defaultLocale adalah Locales.CHINESE dan klien meminta Locales.DUTCH, terjemahan yang dikembalikan akan menggunakan nilai Locales.CHINESE secara default.
• Jika defaultLocale tidak didefinisikan, fungsi t akan kembali menggunakan nilai Locales.ENGLISH.

Penegakan Mode Ketat

Konfigurasikan fungsi t untuk menegakkan kepatuhan ketat terhadap locale yang dideklarasikan:

Contoh Konfigurasi:

import { type IntlayerConfig } from "intlayer";

const config = {
  // ... Konfigurasi Anda yang sudah ada
  internationalization: {
    // ... Konfigurasi internationalization Anda yang sudah ada
    strictMode: "strict", // Terapkan mode ketat
  },
} satisfies IntlayerConfig;

export default config;

Integrasi TypeScript

Fungsi t aman tipe saat digunakan dengan TypeScript. Definisikan objek terjemahan yang aman tipe:

import { type LanguageContent } from "express-intlayer";

const translations: LanguageContent<string> = {
  en: "Selamat pagi!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (_req, res) => {
  res.send(t(translations));
});

Kesalahan Umum dan Pemecahan Masalah

Tips untuk Penggunaan Efektif

1. Sentralisasi Terjemahan: Gunakan modul terpusat atau file JSON untuk mengelola terjemahan agar memudahkan pemeliharaan.
2. Validasi Terjemahan: Pastikan setiap varian bahasa memiliki terjemahan yang sesuai untuk mencegah fallback yang tidak perlu.
3. Gabungkan dengan i18n Frontend: Sinkronkan dengan internasionalisasi frontend untuk pengalaman pengguna yang mulus di seluruh aplikasi.
4. Uji Kinerja: Uji waktu respons aplikasi Anda saat menambahkan terjemahan untuk memastikan dampak minimal.

Kesimpulan

Fungsi t adalah alat yang kuat untuk internasionalisasi backend. Dengan menggunakannya secara efektif, Anda dapat membuat aplikasi yang lebih inklusif dan ramah pengguna untuk audiens global. Untuk penggunaan lanjutan dan opsi konfigurasi yang lebih rinci, lihat dokumentasi.