Ajukan pertanyaan Anda dan dapatkan ringkasan dokumen dengan merujuk halaman ini dan penyedia AI pilihan Anda
Riwayat Versi
- "Perbarui penggunaan API useIntlayer Solid ke akses properti langsung"v8.9.04/5/2026
- "Ditambahkan untuk Tanstack Start Solid.js"v8.5.125/3/2026
Konten halaman ini diterjemahkan menggunakan AI.
Lihat versi terakhir dari konten aslinya dalam bahasa InggrisJika Anda memiliki ide untuk meningkatkan dokumentasi ini, silakan berkontribusi dengan mengajukan pull request di GitHub.
Tautan GitHub ke dokumentasiSalin Markdown dokumentasi ke clipboard
Terjemahkan situs web Tanstack Start + Solid.js Anda menggunakan Intlayer | Internasionalisasi (i18n)
Daftar Isi
Panduan ini mendemonstrasikan cara mengintegrasikan Intlayer untuk internasionalisasi yang mulus dalam proyek Tanstack Start dengan Solid.js, perutean yang sadar akan lokal (locale-aware), dukungan TypeScript, dan praktik pengembangan modern.
Apa itu Intlayer?
Intlayer adalah perpustakaan internasionalisasi (i18n) inovatif dan sumber terbuka yang dirancang untuk menyederhanakan dukungan multibahasa dalam aplikasi web modern.
Dengan Intlayer, Anda dapat:
- Mengelola terjemahan dengan mudah menggunakan kamus deklaratif di tingkat komponen.
- Melokalisasi metadata, rute, dan konten secara dinamis.
- Memastikan dukungan TypeScript dengan tipe yang dihasilkan secara otomatis, meningkatkan pelengkapan otomatis (autocompletion) dan deteksi kesalahan.
- Memanfaatkan fitur-fitur canggih, seperti deteksi dan pengalihan lokal secara dinamis.
- Mengaktifkan perutean yang sadar akan lokal dengan sistem perutean berbasis file Milik Tanstack Start.
Panduan Langkah-demi-Langkah Pengaturan Intlayer di Aplikasi Tanstack Start
Lihat Templat Aplikasi di GitHub.
Langkah 1: Pembuatan Proyek
Pertama, buat proyek TanStack Start baru mengikuti panduan Memulai Proyek Baru di situs web TanStack Start.
Langkah 2: Instal Paket Intlayer
Instal paket-paket yang diperlukan menggunakan pengelola paket pilihan Anda:
Salin kode ke clipboard
npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer initintlayer
Paket inti yang menyediakan alat internasionalisasi untuk manajemen konfigurasi, terjemahan, deklarasi konten, transpilasi, dan perintah CLI.
solid-intlayer Paket yang mengintegrasikan Intlayer ke dalam aplikasi Solid. Paket ini menyediakan penyedia konteks (context providers) dan hook untuk internasionalisasi Solid.
vite-intlayer Menyertakan plugin Vite untuk mengintegrasikan Intlayer dengan Vite bundler, serta middleware untuk mendeteksi lokal pilihan pengguna, mengelola cookie, dan menangani pengalihan URL.
Langkah 3: Konfigurasi Proyek Anda
Buat file konfigurasi untuk mengatur bahasa aplikasi Anda:
Salin kode ke clipboard
import type { IntlayerConfig } from "intlayer";import { Locales } from "intlayer";const config: IntlayerConfig = { internationalization: { defaultLocale: Locales.ENGLISH, locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], },};export default config;Melalui file konfigurasi ini, Anda dapat mengonfigurasi URL yang dilokalisasi, pengalihan middleware, nama cookie, lokasi dan ekstensi deklarasi konten Anda, menonaktifkan log Intlayer di konsol, dan banyak lagi. Untuk daftar lengkap parameter yang tersedia, lihat dokumentasi konfigurasi.
Langkah 4: Integrasikan Intlayer dalam Konfigurasi Vite Anda
Tambahkan plugin intlayer dalam konfigurasi Anda:
Salin kode ke clipboard
import { intlayer } from "vite-intlayer";import { defineConfig } from "vite";import { devtools } from "@tanstack/devtools-vite";import { tanstackStart } from "@tanstack/solid-start/plugin/vite";import solidPlugin from "vite-plugin-solid";export default defineConfig({ plugins: [ devtools(), tanstackStart({ router: { routeFileIgnorePattern: ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$", }, }), solidPlugin({ ssr: true }), intlayer(), ],});Plugin Vite intlayer() digunakan untuk mengintegrasikan Intlayer dengan Vite. Plugin ini memastikan pembuatan file deklarasi konten dan memantaunya dalam mode pengembangan. Plugin ini mendefinisikan variabel lingkungan Intlayer dalam aplikasi Vite. Selain itu, ia menyediakan alias untuk mengurangi beban performa.
Langkah 5: Buat Root Layout
Konfigurasikan root layout Anda untuk mendukung internasionalisasi dengan menggunakan useParams untuk mendeteksi lokal saat ini dan mengatur atribut lang serta dir pada tag html.
Salin kode ke clipboard
import { HeadContent, Scripts, createRootRouteWithContext,} from "@tanstack/solid-router";import { HydrationScript } from "solid-js/web";import { Suspense, type ParentComponent } from "solid-js";import { IntlayerProvider } from "solid-intlayer";import { defaultLocale, getHTMLTextDir } from "intlayer";import { Route as LocaleRoute } from "./{-$locale}/route";export const Route = createRootRouteWithContext()({ shellComponent: RootComponent,});const RootComponent: ParentComponent = (props) => { const params = LocaleRoute.useParams(); const locale = params()?.locale ?? defaultLocale; return ( <html dir={getHTMLTextDir(locale)} lang={locale}> <head> <HydrationScript /> <HeadContent /> </head> <body> <IntlayerProvider locale={locale}> <Suspense>{props.children}</Suspense> </IntlayerProvider> <Scripts /> </body> </html> );};Langkah 6: Buat Locale Layout (Opsional)
Buat layout yang menangani prefiks lokal dan melakukan validasi. Layout ini akan memastikan hanya lokal yang valid yang diproses.
Langkah ini opsional jika Anda tidak perlu memvalidasi prefiks lokal pada tingkat rute.
Salin kode ke clipboard
import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";import { validatePrefix } from "intlayer";export const Route = createFileRoute("/{-$locale}")({ beforeLoad: ({ params }) => { const localeParam = params.locale; // Memvalidasi prefiks lokal const { isValid, localePrefix } = validatePrefix(localeParam); if (!isValid) { throw redirect({ to: "/{-$locale}/404", params: { locale: localePrefix }, replace: true, }); } }, component: Outlet,});Di sini,{-$locale}adalah parameter rute dinamis yang digantikan oleh lokal saat ini. Notasi ini membuat slot tersebut opsional, memungkinkannya bekerja dengan mode perutean seperti'prefix-no-default'dll.
Perlu diketahui bahwa slot ini dapat menyebabkan masalah jika Anda menggunakan beberapa segmen dinamis dalam rute yang sama (misal:
/{-$locale}/other-path/$anotherDynamicPath/...). Untuk mode'prefix-all', Anda mungkin lebih suka mengganti slot tersebut menjadi$locale. Untuk mode'no-prefix'atau'search-params', Anda dapat menghapus slot tersebut sepenuhnya.
Langkah 7: Deklarasikan Konten Anda
Buat dan kelola deklarasi konten Anda untuk menyimpan terjemahan:
Salin kode ke clipboard
import type { Dictionary } from "intlayer";import { t } from "intlayer";const appContent = { content: { links: { about: t({ en: "About", es: "Acerca de", fr: "À propos", }), home: t({ en: "Home", es: "Inicio", fr: "Accueil", }), }, meta: { title: t({ en: "Welcome to Intlayer + TanStack Router", es: "Bienvenido a Intlayer + TanStack Router", fr: "Bienvenue à Intlayer + TanStack Router", }), description: t({ en: "This is an example of using Intlayer with TanStack Router", es: "Este es un ejemplo de uso de Intlayer con TanStack Router", fr: "Ceci est un exemple d'utilisation d'Intlayer dengan TanStack Router", }), }, }, key: "app",} satisfies Dictionary;export default appContent;Deklarasi konten Anda dapat didefinisikan di mana saja dalam aplikasi Anda, selama disertakan dalam direktoricontentDir(secara default,./app). Dan harus memiliki ekstensi file deklarasi konten (secara default,.content.{json,ts,tsx,js,jsx,mjs,cjs}).
Untuk detail lebih lanjut, lihat dokumentasi deklarasi konten.
Langkah 8: Gunakan Komponen dan Hook yang Sadar akan Lokal
Buat komponen LocalizedLink untuk navigasi yang sadar akan lokal:
Salin kode ke clipboard
import { Link, type LinkProps } from "@tanstack/solid-router";import { getPrefix } from "intlayer";import { useLocale } from "solid-intlayer";import type { JSX } from "solid-js";export const LOCALE_ROUTE = "{-$locale}" as const;export type RemoveLocaleParam<TVal> = TVal extends string ? RemoveLocaleFromString<TVal> : TVal;export type To = RemoveLocaleParam<LinkProps["to"]>;type CollapseDoubleSlashes<TString extends string> = TString extends `${infer THead}//${infer TTail}` ? CollapseDoubleSlashes<`${THead}/${TTail}`> : TString;export type LocalizedLinkProps = Omit<LinkProps, "to"> & { to?: To;} & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;type RemoveAll< TString extends string, TSub extends string,> = TString extends `${infer THead}${TSub}${infer TTail}` ? RemoveAll<`${THead}${TTail}`, TSub> : TString;type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes< RemoveAll<TString, typeof LOCALE_ROUTE>>;export const LocalizedLink = (props: LocalizedLinkProps) => { const { locale } = useLocale(); return ( <Link {...props} params={{ locale: getPrefix(locale()).localePrefix, ...(typeof props.params === "object" ? props.params : {}), }} to={`/${LOCALE_ROUTE}${props.to ?? ""}` as LinkProps["to"]} /> );};Komponen ini melayani dua tujuan:
- Menghapus prefiks
{-$locale}yang tidak perlu dari URL. - Menyuntikkan parameter lokal ke dalam URL untuk memastikan pengguna diarahkan langsung ke rute yang dilokalisasi.
Kemudian, kita dapat membuat hook useLocalizedNavigate untuk navigasi programatik:
Salin kode ke clipboard
import { useNavigate } from "@tanstack/solid-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: string) => { const localizedTo = getLocalizedUrl(to, locale()); return navigate({ to: localizedTo }); }; return localizedNavigate;};Langkah 9: Gunakan Intlayer di Halaman Anda
Akses kamus konten Anda di seluruh aplikasi:
Halaman Beranda yang Dilokalisasi
Salin kode ke clipboard
import { createFileRoute } from "@tanstack/solid-router";import { useIntlayer } from "solid-intlayer";import { LocalizedLink } from "@/components/LocalizedLink";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent,});function RouteComponent() { const content = useIntlayer("index-page"); return ( <main> <h1>{content.heroTitle}</h1> <p>{content.heroDesc}</p> <div> <LocalizedLink to="/">{content.navHome}</LocalizedLink> <LocalizedLink to="/about">{content.navAbout}</LocalizedLink> </div> </main> );}Jika Anda ingin menggunakan konten Anda dalam atributstring, sepertialt,title,href,aria-label, dll., Anda harus memanggil nilai fungsi tersebut, seperti:
htmlSalin kodeSalin kode ke clipboard
<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />
In Solid,
useIntlayerreturns reactive content (e.g.,content). You can access its properties directly.Untuk mempelajari lebih lanjut tentang hook
useIntlayer, lihat dokumentasi.
Langkah 10: Buat Komponen Locale Switcher
Buat komponen yang memungkinkan pengguna untuk mengubah bahasa:
Salin kode ke clipboard
import { useLocation } from "@tanstack/solid-router";import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";import { For } from "solid-js";import { useIntlayer, useLocale } from "solid-intlayer";import { LocalizedLink, type To } from "./LocalizedLink";export const LocaleSwitcher = () => { const content = useIntlayer("locale-switcher"); const location = useLocation(); const { availableLocales, locale, setLocale } = useLocale(); const pathWithoutLocale = () => getPathWithoutLocale(location().pathname); return ( <div class="flex flex-row gap-2"> <For each={availableLocales}> {(localeEl) => ( <LocalizedLink aria-current={localeEl === locale() ? "page" : undefined} onClick={() => setLocale(localeEl)} params={{ locale: getPrefix(localeEl).localePrefix }} to={pathWithoutLocale() as To} > {getLocaleName(localeEl)} </LocalizedLink> )} </For> </div> );};export default LocaleSwitcher;Dalam file Solid,
localedariuseLocaleadalah sebuah signal accessor. Gunakanlocale()(dengan tanda kurung) untuk membaca nilai saat ini secara reaktif.Untuk mempelajari lebih lanjut tentang hook
useLocale, lihat dokumentasi.
Langkah 11: Pengelolaan Atribut HTML
Seperti yang terlihat pada Langkah 5, Anda dapat mengelola atribut lang dan dir dari tag html dengan menggunakan useParams di root component Anda. Ini memastikan atribut yang benar disetel baik di server maupun klien.
Salin kode ke clipboard
const RootComponent: ParentComponent = (props) => { const params = LocaleRoute.useParams(); const locale = params()?.locale ?? defaultLocale; return ( <html dir={getHTMLTextDir(locale)} lang={locale}> {/* ... */} </html> );};Langkah 12: Tambahkan Middleware (Opsional)
Anda juga dapat menggunakan intlayerProxy untuk menambahkan perutean sisi server ke aplikasi Anda. Plugin ini secara otomatis akan mendeteksi lokal saat ini berdasarkan URL dan mengatur cookie lokal yang sesuai. Jika tidak ada lokal yang ditentukan, plugin akan menentukan lokal yang paling tepat berdasarkan preferensi bahasa browser pengguna. Jika tidak ada lokal yang terdeteksi, ia akan mengalihkan ke lokal default.
Perlu diketahui bahwa untuk menggunakanintlayerProxydalam produksi, Anda perlu memindahkan paketvite-intlayerdaridevDependencieskedependencies.
Salin kode ke clipboard
import { tanstackStart } from "@tanstack/solid-start/plugin/vite";import solid from "vite-plugin-solid";import { nitro } from "nitro/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({ plugins: [ intlayerProxy(), // Proxy harus ditempatkan sebelum server jika Anda menggunakan Nitro nitro(), intlayer(), tanstackStart({ router: { routeFileIgnorePattern: ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$", }, }), solid(), ],});Langkah 13: Internasionalisasi Metadata Anda (Opsional)
Anda juga dapat menggunakan fungsi getIntlayer untuk mengakses kamus konten Anda dalam head loader untuk metadata yang sadar akan lokal:
Salin kode ke clipboard
import { createFileRoute } from "@tanstack/solid-router";import { getIntlayer } from "intlayer";export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: ({ params }) => { const { locale } = params; const path = "/"; // The path for this route const metaContent = getIntlayer("app", locale); return { links: [ // Canonical link: Points to the current localized page { rel: "canonical", href: getLocalizedUrl(path, locale) }, // Hreflang: Tell Google about all localized versions ...localeMap(({ locale: mapLocale }) => ({ rel: "alternate", hrefLang: mapLocale, href: getLocalizedUrl(path, mapLocale), })), // x-default: For users in unmatched languages // Define the default fallback locale (usually your primary language) { rel: "alternate", hrefLang: "x-default", href: getLocalizedUrl(path, defaultLocale), }, ], meta: [ { title: metaContent.title }, { name: "description", content: metaContent.meta.description }, ], }; },});Langkah 14: Ambil lokal di server action Anda (Opsional)
Anda mungkin ingin mengakses lokal saat ini dari dalam server action atau titik akhir API Anda.
Anda dapat melakukan ini menggunakan helper getLocale dari intlayer.
Berikut adalah contoh penggunaan fungsi server TanStack Start:
Salin kode ke clipboard
import { createServerFn } from "@tanstack/solid-start";import { getRequestHeader, getRequestHeaders,} from "@tanstack/solid-start/server";import { getCookie, getIntlayer, getLocale } from "intlayer";export const getLocaleServer = createServerFn().handler(async () => { const locale = await getLocale({ // Mendapatkan cookie dari permintaan (default: 'INTLAYER_LOCALE') getCookie: (name) => { const cookieString = getRequestHeader("cookie"); return getCookie(name, cookieString); }, // Mendapatkan header dari permintaan (default: 'x-intlayer-locale') // Fallback menggunakan negosiasi Accept-Language getHeader: (name) => getRequestHeader(name), }); // Ambil beberapa konten menggunakan getIntlayer() const content = getIntlayer("app", locale); return { locale, content };});Langkah 15: Mengelola halaman "not found" (Opsional)
Saat pengguna mengunjungi halaman yang tidak ada, Anda dapat menampilkan halaman kustom "not found" dan prefiks lokal dapat memengaruhi cara halaman "not found" tersebut dipicu.
Memahami penanganan 404 TanStack Router dengan prefiks lokal
Di TanStack Router, menangani halaman 404 dengan rute yang dilokalisasi memerlukan pendekatan berlapis:
- Rute 404 khusus: Rute spesifik untuk menampilkan UI 404
- Validasi tingkat rute: Memvalidasi prefiks lokal dan mengalihkan prefiks yang tidak valid ke 404
- Rute catch-all: Menangkap setiap jalur yang tidak cocok dalam segmen lokal
Salin kode ke clipboard
import { createFileRoute } from "@tanstack/solid-router";// Ini membuat rute /[locale]/404 khusus// Digunakan baik sebagai rute langsung maupun diimpor sebagai komponen di file lainexport const Route = createFileRoute("/{-$locale}/404")({ component: NotFoundComponent,});// Diekspor secara terpisah agar bisa digunakan kembali di notFoundComponent dan rute catch-allexport function NotFoundComponent() { return ( <div> <h1>404</h1> </div> );}Salin kode ke clipboard
import { createFileRoute, Outlet, redirect } from "@tanstack/solid-router";import { validatePrefix } from "intlayer";import { NotFoundComponent } from "./404";export const Route = createFileRoute("/{-$locale}")({ // beforeLoad berjalan sebelum rute dirender (baik di server maupun klien) // Ini adalah tempat yang ideal untuk memvalidasi prefiks lokal beforeLoad: ({ params }) => { const localeParam = params.locale; // validatePrefix memeriksa apakah lokal valid sesuai dengan konfigurasi intlayer Anda const { isValid, localePrefix } = validatePrefix(localeParam); if (!isValid) { // Prefiks lokal tidak valid - alihkan ke halaman 404 dengan prefiks lokal yang valid throw redirect({ to: "/{-$locale}/404", params: { locale: localePrefix }, }); } }, component: Outlet, // notFoundComponent dipanggil ketika rute anak tidak ada // misal: /en/halaman-tidak-ada memicu ini dalam layout /en notFoundComponent: NotFoundComponent,});Salin kode ke clipboard
import { createFileRoute } from "@tanstack/solid-router";import { NotFoundComponent } from "./404";// Rute $ (splat/catch-all) cocok dengan jalur apa pun yang tidak cocok dengan rute lain// misal: /en/beberapa/jalur/dalam/yang/tidak/valid// Ini memastikan SEMUA jalur yang tidak cocok dalam sebuah lokal menampilkan halaman 404// Tanpa ini, jalur dalam yang tidak cocok mungkin menampilkan halaman kosong atau kesalahanexport const Route = createFileRoute("/{-$locale}/$")({ component: NotFoundComponent,});(Opsional) Langkah 16: Ekstrak konten dari komponen Anda
Jika Anda memiliki basis kode yang sudah ada, mengubah ribuan file bisa memakan waktu lama.
Untuk mempermudah proses ini, Intlayer mengusulkan sebuah konpiler / ekstraktor untuk mentransformasi komponen Anda dan mengekstrak kontennya.
Untuk mengaturnya, Anda dapat menambahkan bagian compiler di file intlayer.config.ts Anda:
Salin kode ke clipboard
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... Sisa konfigurasi Anda
compiler: {
/**
* Menandakan apakah kompiler harus diaktifkan.
*/
enabled: true,
/**
* Mendefinisikan jalur file keluaran
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* Menandakan apakah komponen harus disimpan setelah ditransformasikan.
*
* - Jika `true`, kompiler akan menulis ulang file komponen di disk. Dengan demikian, transformasi akan permanen, dan kompiler akan melewati transformasi untuk proses selanjutnya. Dengan cara ini, kompiler dapat mentransformasi aplikasi dan kemudian dapat dihapus.
*
* - Jika `false`, kompiler hanya akan menyuntikkan pemanggilan fungsi `useIntlayer()` dalam kode hanya di output build, menjaga basis kode asli tetap utuh. Transformasi hanya akan dilakukan di memori.
*/
saveComponents: false,
/**
* Prefiks kunci kamus
*/
dictionaryKeyPrefix: "",
},
};
export default config;Jalankan ekstraktor untuk mentransformasi komponen Anda dan mengekstrak kontennya
Salin kode ke clipboard
npx intlayer extractLangkah 17: Konfigurasi TypeScript (Opsional)
Intlayer menggunakan module augmentation untuk mendapatkan manfaat TypeScript dan membuat basis kode Anda lebih kuat.
Pastikan konfigurasi TypeScript Anda menyertakan tipe yang dihasilkan secara otomatis:
Salin kode ke clipboard
{ // ... pengaturan Anda yang sudah ada include: [ // ... penyertaan Anda yang sudah ada ".intlayer/**/*.ts", // Sertakan tipe yang dihasilkan secara otomatis ],}Konfigurasi Git
Disarankan untuk mengabaikan file yang dihasilkan oleh Intlayer. Ini memungkinkan Anda untuk menghindari melakukan komit file tersebut ke repositori Git Anda.
Untuk melakukan ini, Anda dapat menambahkan instruksi berikut ke file .gitignore Anda:
Salin kode ke clipboard
# Abaikan file yang dihasilkan oleh Intlayer.intlayerEkstensi VS Code
Untuk meningkatkan pengalaman pengembangan Anda dengan Intlayer, Anda dapat menginstal Ekstensi VS Code Intlayer resmi.
Instal dari VS Code Marketplace
Ekstensi ini menawarkan:
- Autocompletion untuk kunci terjemahan.
- Deteksi kesalahan waktu nyata (real-time) untuk terjemahan yang hilang.
- Pratinjau inline dari konten yang diterjemahkan.
- Quick actions untuk membuat dan memperbarui terjemahan dengan mudah.
Untuk detail lebih lanjut tentang cara menggunakan ekstensi ini, lihat dokumentasi Ekstensi VS Code Intlayer.
Langkah Lebih Lanjut
Untuk melangkah lebih jauh, Anda dapat mengimplementasikan visual editor atau mengeksternalisasi konten Anda menggunakan CMS.