Y datrysiad gorau ar gyfer rhyngwladoli (i18n) mewn apiau Next.js

Sut mae'n gweithio

Wrth i'r byd ddod yn fwy byd-eang, mae'n dod yn 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 ryngwladoliad (i18n), sy'n eich galluogi i addasu eich cais i wahanol ieithoedd, arianau, a fformatau dyddiad.

Yn y tiwtorial hwn, byddwn yn archwilio sut i ychwanegu rhyngwladoliad i'ch cais React Next.js, gyda rendro ar ochr y gweinydd. TL;DR: Gweler yr enghraifft lawn yma.

Mae'r canllaw hwn ar gyfer cymwysiadau Next.js sy'n defnyddio Pages Router.
Os ydych yn defnyddio'r App Router, gweler y canllaw hwn yn hytrach.

Cam 1: Gosod llyfrgell i18n

Er mwyn gweithredu rhyngwladoli yn eich cais Next.js, byddwn ni'n dewis llyfrgell i18n yn gyntaf. Mae sawl llyfrgell boblogaidd, gan gynnwys next-intl. Fodd bynnag, yn yr enghraifft hon, byddwn ni'n defnyddio TacoTranslate.

Mae TacoTranslate yn cyfieithu eich llinynnau'n awtomatig i unrhyw iaith gan ddefnyddio AI blaengar, ac yn eich rhyddhau o'r gwaith diflas o reoli ffeiliau JSON.

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

npm install tacotranslate

Cam 2: Creu cyfrif TacoTranslate am ddim

Nawr eich bod wedi gosod y modiwl, mae'n bryd creu eich cyfrif TacoTranslate, prosiect cyfieithu, a'r allweddi API cysylltiedig. Creu cyfrif yma. Mae'n rhad ac am ddim, ac nid yw'n gofyn i chi ychwanegu cerdyn credyd.

Yn rhyngwyneb y cymhwysiad TacoTranslate, creuwch brosiect a llywiwch i'r tab allweddi API. Creuwch un allwedd read a un allwedd read/write. Byddwn yn eu cadw fel newidynnau amgylcheddol. Y allwedd read yw'r hyn a elwir gennym yn public a'r allwedd read/write yw secret. Er enghraifft, gallech eu hychwanegu at ffeil .env yn y cyfeiriadur gwraidd eich prosiect.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gwnewch yn siŵr na fyddwch byth yn datgelu'r allwedd API gyfrinachol read/write i amgylcheddau cynhyrchu ar ochr y cleient.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Cod y lleoliad diofyn a ddefnyddir fel ateb wrth fethu. Yn yr enghraifft hon, byddwn yn ei osod i en ar gyfer Saesneg.
• TACOTRANSLATE_ORIGIN: Y “ffolder” lle bydd eich stringiau yn cael eu storio, megis URL eich gwefan. Darllenwch fwy am darddiadau yma.

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

Cam 3: Gosod TacoTranslate

Er mwyn integreiddio TacoTranslate gyda’ch cymhwysiad, bydd rhaid i chi greu cleient gan ddefnyddio'r allweddi API a gafodd eu creu 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Byddwn yn diffinio TACOTRANSLATE_API_KEY yn awtomatig yn fuan.

Mae creu'r cleient mewn ffeil ar wahân yn ei gwneud yn haws ei ddefnyddio eto yn ddiweddarach. Nawr, gan ddefnyddio /pages/_app.tsx wedi'i haddasu, byddwn ni'n ychwanegu'r darparwr TacoTranslate.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Os oes gennych eisoes pageProps a _app.tsx, estynnwch y diffiniad gyda'r eiddo a'r cod uchod, os gwelwch yn dda.

Cam 4: Gweithredu rendro ar ochr y gweinydd

Mae TacoTranslate yn caniatáu rendro ochr-y-gweinydd ar gyfer eich cyfieithiadau. Mae hyn yn gwella profiad y defnyddiwr yn fawr trwy ddangos cynnwys wedi’i gyfieithu ar unwaith, yn hytrach na fflach o gynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn hepgor ceisiadau rhwydwaith ar y cleient, gan ein bod eisoes â’r holl gyfieithiadau sydd eu hangen arnom.

Dechreufwn trwy greu neu olygu /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

Addaswch y gwiriad isProduction i weddu i’ch gosodiad. Os yw true, bydd TacoTranslate yn amlygu'r allwedd API gyhoeddus. Os ydym mewn amgylchedd lleol, prawf neu staging (isProduction is false), byddwn yn defnyddio'r allwedd API gyfrinachol read/write i sicrhau bod llinynnau newydd yn cael eu hanfon at gyfieithu.

Hyd yn hyn, rydyn ni wedi sefydlu'r cais Next.js yn unig gyda rhestr o ieithoedd a gefnogir. Y cam nesaf yw nôl cyfieithiadau ar gyfer eich holl dudalennau. I wneud hynny, fe ddefnyddiwch naill ai getTacoTranslateStaticProps neu getTacoTranslateServerSideProps yn dibynnu ar eich gofynion.

Mae'r swyddogaethau hyn yn cymryd tri dadleuon: un gwrthrych Next.js Static Props Context, ffurfweddiad ar gyfer TacoTranslate, a eiddo Next.js dewisol. Sylwch fod revalidate ar getTacoTranslateStaticProps wedi'i osod i 60 yn ddiofyn, fel bod eich cyfieithiadau'n aros yn gyfredol.

I ddefnyddio unrhyw un o'r swyddogaethau hyn mewn tudalen, gadewch i ni dybio bod gennych ffeil tudalen fel /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Dylech nawr allu defnyddio'r cydran Translate i gyfieithu'r testunau ym mhob un o'ch cydrannau React.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Cam 5: Cyhoeddi a phrofi!

Rydym ni wedi gorffen! Bydd eich cais Next.js bellach yn cael ei gyfieithu'n awtomatig pan fyddwch chi'n ychwanegu unrhyw llinynnau at gydran Translate. Sylwch bod dim ond amgylcheddau â chaniatâd read/write ar allwedd API fydd yn gallu creu llinynnau newydd i'w cyfieithu. Rydym yn argymell cael amgylchedd paratoi caeedig a diogel lle gallwch 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 efallai hefyd yn achosi i'ch prosiect cyfieithu fynd yn orlawn drwy ychwanegu llinynnau newydd nad ydynt yn gysylltiedig.

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 App 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!