Kuinka toteuttaa kansainvälistäminen Next.js-sovelluksessa, joka käyttää App Router -reititintä
Tee React-sovelluksestasi entistä saavutettavampi ja laajenna uusille markkinoille kansainvälistämisen (i18n) avulla.
Maailman muuttuessa yhä globaalimmaksi, on verkkokehittäjille yhä tärkeämpää rakentaa sovelluksia, jotka palvelevat käyttäjiä eri maista ja kulttuureista. Yksi keskeisistä keinoista tämän saavuttamiseksi on kansainvälistäminen (i18n), joka mahdollistaa sovelluksen mukauttamisen eri kielille, valuutoille ja päivämäärämuodoille.
Tässä artikkelissa perehdymme siihen, miten voit lisätä kansainvälistämisen React Next.js -sovellukseesi, hyödyntäen server side rendering -tekniikkaa. TL;DR: Katso koko esimerkki täältä.
Tämä opas on tarkoitettu Next.js-sovelluksille, jotka käyttävät App Router-reititystä.
Jos käytät Pages Router-reititystä, katso sen sijaan tämä opas.
Vaihe 1: Asenna i18n-kirjasto
Kansainvälistämisen (i18n) toteuttamiseksi Next.js-sovelluksessasi valitsemme ensin i18n-kirjaston. Saatavilla on useita suosittuja kirjastoja, mukaan lukien next-intl. Tässä esimerkissä käytämme kuitenkin TacoTranslate.
TacoTranslate kääntää merkkijonosi automaattisesti mihin tahansa kieleen edistyneen tekoälyn avulla ja vapauttaa sinut JSON-tiedostojen työläästä hallinnasta.
Asennetaan se käyttämällä npm komentorivilläsi:
npm install tacotranslate
Vaihe 2: Luo ilmainen TacoTranslate-tili
Nyt kun moduuli on asennettu, on aika luoda TacoTranslate-tili, käännösprojekti ja siihen liittyvät API-avaimet. Luo tili tästä. Se on ilmainen, eikä vaadi luottokortin lisäämistä.
TacoTranslate-sovelluksen käyttöliittymässä luo projekti ja siirry sen API-avaimet-välilehdelle. Luo yksi read
avain ja yksi read/write
avain. Tallennamme ne ympäristömuuttujina. read
avainta kutsumme public
ja read/write
avain on secret
. Voit esimerkiksi lisätä ne .env
-tiedostoon projektisi juureen.
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010
Varmista, ettet koskaan vuoda salaista read/write
API-avainta asiakaspuolen tuotantoympäristöihin.
Lisäämme myös kaksi muuta ympäristömuuttujaa: TACOTRANSLATE_DEFAULT_LOCALE
ja TACOTRANSLATE_ORIGIN
.
TACOTRANSLATE_DEFAULT_LOCALE
: Oletusarvoinen varapaikkakoodin kieli. Tässä esimerkissä asetamme sen arvoonen
englannille.TACOTRANSLATE_ORIGIN
: "Kansio", johon merkkisi tallennetaan, esimerkiksi verkkosivustosi URL-osoite. Lue lisää originaaleista tästä.
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com
Vaihe 3: TacoTranslate:n asentaminen
TacoTranslate-integroimiseksi sovellukseesi sinun täytyy luoda client käyttämällä aiemmin annettuja API-avaimia. Esimerkiksi luo tiedosto nimeltä /tacotranslate-client.js
.
const {default: createTacoTranslateClient} = require('tacotranslate');
const tacoTranslate = createTacoTranslateClient({
apiKey:
process.env.TACOTRANSLATE_SECRET_API_KEY ??
process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
process.env.TACOTRANSLATE_API_KEY,
projectLocale:
process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
? process.env.TACOTRANSLATE_PROJECT_LOCALE
: undefined,
});
module.exports = tacoTranslate;
Määrittelemme pian automaattisesti TACOTRANSLATE_API_KEY
ja TACOTRANSLATE_PROJECT_LOCALE
.
Clientin luominen erilliseen tiedostoon tekee sen uudelleenkäytöstä helppoa. getLocales
on vain apufunktio, jossa on sisäänrakennettua virheenkäsittelyä. Luo nyt tiedosto nimeltä /app/[locale]/tacotranslate.tsx
, johon toteutamme TacoTranslate
providerin.
'use client';
import React, {type ReactNode} from 'react';
import {
type TranslationContextProperties,
TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';
export default function TacoTranslate({
locale,
origin,
localizations,
children,
}: TranslationContextProperties & {
readonly children: ReactNode;
}) {
return (
<ImportedTacoTranslate
client={tacoTranslateClient}
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</ImportedTacoTranslate>
);
}
Huomaa 'use client';
, joka ilmaisee, että tämä on client-komponentti.
Nyt kun kontekstin tarjoaja on valmis, luo tiedosto nimeltä /app/[locale]/layout.tsx
, sovelluksemme juurilayout. Huomaa, että tämä polku sisältää kansion, joka käyttää Dynamic Routes, missä [locale]
on dynaaminen parametri.
import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';
export async function generateStaticParams() {
const locales = await tacoTranslateClient.getLocales();
return locales.map((locale) => ({locale}));
}
type RootLayoutParameters = {
readonly params: Promise<{locale: Locale}>;
readonly children: ReactNode;
};
export default async function RootLayout({params, children}: RootLayoutParameters) {
const {locale} = await params;
const origin = process.env.TACOTRANSLATE_ORIGIN;
const localizations = await tacoTranslateClient.getLocalizations({
locale,
origins: [origin /* , other origins to fetch */],
});
return (
<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
<body>
<TacoTranslate
locale={locale}
origin={origin}
localizations={localizations}
>
{children}
</TacoTranslate>
</body>
</html>
);
}
Ensimmäinen asia, johon kannattaa kiinnittää huomiota, on se, että käytämme Dynamic Route
-parametriasetta [locale]
hakemaan käännökset kyseiselle kielelle. Lisäksi generateStaticParams
varmistaa, että kaikki projektissasi aktivoidut kielikoodit esirendataan.
Rakennetaan nyt ensimmäinen sivumme! Luo tiedosto nimeltä /app/[locale]/page.tsx
.
import React from 'react';
import {Translate} from 'tacotranslate/react';
export const revalidate = 60;
export default async function Page() {
return (
<Translate string="Hello, world!" />
);
}
Huomaa revalidate
muuttuja, joka kertoo Next.js:lle, että sivu rakennetaan uudelleen 60 sekunnin välein ja että käännöksesi pysyvät ajan tasalla.
Vaihe 4: Palvelinpuolen renderöinnin toteuttaminen
TacoTranslate tukee palvelinpuolen renderöintiä. Tämä parantaa käyttäjäkokemusta merkittävästi näyttämällä käännetyn sisällön välittömästi sen sijaan, että ensin ilmaantuisi hetken ajan kääntämätön sisältö. Lisäksi voimme ohittaa verkkopyynnöt asiakkaan puolella, koska meillä on jo tarvittavat käännökset käyttäjän katsomalle sivulle.
Palvelinpuolen renderöinnin määrittämiseksi luo tai muokkaa /next.config.js
:
const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');
module.exports = async () => {
const config = await withTacoTranslate(
{},
{
client: tacoTranslateClient,
isProduction:
process.env.TACOTRANSLATE_ENV === 'production' ||
process.env.VERCEL_ENV === 'production' ||
(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
process.env.NODE_ENV === 'production'),
}
);
// NOTE: Remove i18n from config when using the app router
return {...config, i18n: undefined};
};
Muokkaa isProduction
-tarkistus vastaamaan asetuksiasi. Jos true
, TacoTranslate käyttää julkista API-avainta. Jos olemme paikallisessa, testi- tai staging-ympäristössä (isProduction
is false
), käytämme salaista read/write
API-avainta varmistaaksemme, että uudet merkkijonot lähetetään käännettäviksi.
Varmistaaksemme, että reititys ja uudelleenohjaus toimivat odotetusti, meidän täytyy luoda tiedosto nimeltä /middleware.ts
. Käyttämällä Middleware, voimme ohjata käyttäjiä sivuille, jotka esitetään heidän mieltyneellä kielellään.
import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';
export const config = {
matcher: ['/((?!api|_next|favicon.ico).*)'],
};
export async function middleware(request: NextRequest) {
return tacoTranslateMiddleware(tacoTranslate, request);
}
Varmista, että määrität matcher
-asetuksen Next.js Middleware -dokumentaation mukaisesti.
Asiakaspuolella voit muuttaa locale
evästettä vaihtaaksesi käyttäjän preferredist kielestä. Katso täydellinen esimerkkikoodi ideoita varten, miten tämä tehdään!
Vaihe 5: Julkaise ja testaa!
Olemme valmiita! React-sovelluksesi käännetään nyt automaattisesti, kun lisäät merkkijonoja Translate
-komponenttiin. Huomaa, että vain ympäristöt, joilla on read/write
-oikeudet API-avaimeen, pystyvät luomaan uusia käännettäviä merkkijonoja. Suosittelemme pitämään suljetun ja suojatun staging-ympäristön, jossa voit testata tuotantosovellustasi tällaisella API-avaimella ja lisätä uusia merkkijonoja ennen julkaisua. Tämä estää ketään varastamasta salaista API-avaintasi ja mahdollisesti kasvattamasta käännösprojektiasi lisäämällä uusia, asiaankuulumattomia merkkijonoja.
Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the Pages Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.
TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!