Sut i weithredu rhyngwladoli mewn ap Next.js sy’n defnyddio’r App Router

Wrth i'r byd ddod yn fwy rhyngwladoli, mae'n fwyfwy pwysig i ddatblygwyr gwe adeiladu ceisiadau sy'n gallu gwasanaethu defnyddwyr o wledydd a diwylliannau gwahanol. Un o'r prif ffyrdd i gyflawni hyn yw trwy rhyngwladoli (i18n), sy'n eich galluogi i addasu eich cais i wahanol ieithoedd, arian cyfred, a fformatau dyddiad.

Yn yr erthygl hon, byddwn yn archwilio sut i ychwanegu rhyngwladoli i'ch cais React Next.js, gyda rendro ochr y gweinydd. TL;DR: Edrychwch ar yr enghraifft lawn yma.

Mae'r canllaw hwn ar gyfer ceisiadau Next.js sy’n defnyddio’r App Router.
Os ydych chi'n defnyddio’r Pages Router, gweler y canllaw hwn yn lle hynny.

Cam 1: Gosod llyfrgell i18n

I weithredu rhyngwladoli yn eich cais Next.js, byddwn yn dewis llyfrgell i18n yn gyntaf. Mae sawl llyfrgell boblogaidd, gan gynnwys next-intl. Yn yr enghraifft hon, fodd bynnag, byddwn yn defnyddio TacoTranslate.

Mae TacoTranslate yn cyfieithu eich llinynnau’n awtomatig i unrhyw iaith gan ddefnyddio AI o’r radd flaenaf, ac yn eich rhyddhau o reoliadau diflas ffeiliau JSON.

Gadewch i ni ei osod gan ddefnyddio npm yn eich terfynell:

npm install tacotranslate

Cam 2: Creu cyfrif TacoTranslate am ddim

Nawr eich bod wedi gosod y modiwl, mae'n bryd creu’ch cyfrif TacoTranslate, prosiect cyfieithu, ac allweddi API cysylltiedig. Creu cyfrif yma. Mae'n rhad ac am ddim, ac dydy hi ddim yn gofyn i chi ychwanegu cerdyn credyd.

O fewn rhyngwyneb defnyddiwr ap TacoTranslate, creu prosiect, a llywio i’r tab allweddi API. Creu un allwedd read a un allwedd read/write. Byddwn yn eu cadw fel amrywiadau amgylcheddol. Y allwedd read yw’r hyn a elwir yn public ac mae’r allwedd read/write yn secret. Er enghraifft, gallech eu hychwanegu at ffeil .env yng nghwreiddyn eich prosiect.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gwnewch yn siŵr nad ydych byth yn datgelu'r allwedd API gyfrinachol read/write i amgylcheddau cynhyrchu ochr cleient.

Byddwn hefyd yn ychwanegu dau newidyn amgylchedd arall: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Y cod iaith wrth gefn diofyn. Yn yr esiampl hon, byddwn yn ei osod i en ar gyfer Saesneg.
• TACOTRANSLATE_ORIGIN: Y “ffolder” lle bydd eich llinynnau yn cael eu storio, fel URL eich gwefan. Darllen mwy am darddiadau yma.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Cam 3: Gosod TacoTranslate

I integreiddio TacoTranslate â'ch cais, bydd angen i chi greu cleient gan ddefnyddio'r allweddi API a nodwyd yn gynharach. Er enghraifft, creu ffeil o'r enw /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;

Byddwn yn diffinio TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE yn awtomatig yn fuan.

Mae creu'r cleient mewn ffeil ar wahân yn ei gwneud yn hawdd ei ddefnyddio eto yn ddiweddarach. getLocales yw dim ond swyddogaeth ddefnyddiol gyda triniad gwallau adeiledig. Nawr, creu ffeil o'r enw /app/[locale]/tacotranslate.tsx, lle byddwn ni'n gweithredu'r darparwr TacoTranslate.

'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>
	);
}

Sylwer ar 'use client'; sy'n nodi bod hwn yn gydran cleient.

Gyda'r darparwr cyd-destun bellach yn barod i fynd, creu ffeil o'r enw /app/[locale]/layout.tsx, y cynllun gwraidd yn ein cais. Sylwch fod gan y llwybr hwn ffolder sy'n defnyddio Dynamic Routes, lle [locale] yw'r paramedr deinamig.

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>
	);
}

Y peth cyntaf i’w nodi yma yw ein bod yn defnyddio ein paramedr Dynamic Route [locale] i nôl cyfieithiadau ar gyfer y iaith honno. Yn ogystal, mae generateStaticParams yn sicrhau bod yr holl godau lleoliad sydd wedi’u galluogi ar eich prosiect yn cael eu rhag-gynhyrchu.

Nawr, gadewch i ni adeiladu ein tudalen gyntaf! Creu ffeil o’r enw /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!" />
	);
}

Nodwch y newidyn revalidate sy’n dweud wrth Next.js ailadeiladu’r dudalen ar ôl 60 eiliad, a chadw eich cyfieithiadau i fyny-â’r amser.

Cam 4: Gweithredu rendro ochr y gweinydd

Mae TacoTranslate yn cefnogi rendro ochr y gweinydd. Mae hyn yn gwella profiad y defnyddiwr yn fawr trwy ddangos cynnwys wedi’i gyfieithu ar unwaith, yn hytrach nag arddangos cynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn hepgor ceisiadau rhwydwaith ar y cleient, gan ein bod eisoes wedi’r cyfieithiadau sydd eu hangen arnom ar gyfer y dudalen mae’r defnyddiwr yn ei gwylio.

I sefydlu rendro ochr y gweinydd, creu neu addasu /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};
};

Addaswch y gwirio isProduction i gyd-fynd â’ch gosodiad. Os yw true, bydd TacoTranslate yn dangos allwedd API cyhoeddus. Os ydym mewn amgylchedd lleol, prawf, neu gamfa (isProduction is false), byddwn yn defnyddio’r allwedd API gyfrinachol read/write i sicrhau bod llinynnau newydd yn cael eu hanfon ar gyfer cyfieithu.

Er mwyn sicrhau bod llwybro a ailgyfeirio yn gweithio fel y disgwylir, bydd angen i ni greu ffeil o’r enw /middleware.ts. Gan ddefnyddio Middleware, gallwn ailgyfeirio defnyddwyr i dudalennau a gyflwynir yn eu hiaith ddewisol.

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);
}

Gwnewch yn siŵr eich bod yn sefydlu’r matcher yn unol â dogfennaeth Next.js Middleware.

Ar y cleient, gallwch addasu'r cwci locale i newid beth yw ieithwedd a ffafria'r defnyddiwr. Edrychwch ar y cod enghreifftiol cyflawn am syniadau ar sut i wneud hyn!

Cam 5: Rhowch wybod ac arholi!

Rydym wedi gorffen! Bydd eich cais React yn cael ei gyfieithu'n awtomatig nawr pan fyddwch chi'n ychwanegu unrhyw llinynnau i gydran Translate. Sylwch mai dim ond amgylcheddau gyda chaniatadau read/write ar y allwedd API fydd yn gallu creu llinynnau newydd i'w cyfieithu. Rydym yn argymell cael amgylchedd prawf caeedig a diogel lle gallwch chi brofi eich cais cynhyrchu gyda allwedd API o'r fath, gan ychwanegu llinynnau newydd cyn mynd yn fyw. Bydd hyn yn atal unrhyw un rhag dwyn eich allwedd API gyfrinachol, ac yn bosibl atal eich prosiect cyfieithu rhag ymledu'n ormodol trwy ychwanegu llinynnau newydd, anghysylltiedig.

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!