TacoTranslate
/
ΤεκμηρίωσηΤιμολόγηση
 
Εκπαιδευτικό υλικό
04 Μαΐ

Πώς να υλοποιήσετε την διεθνοποίηση σε μια εφαρμογή Next.js που χρησιμοποιεί το App Router

Κάντε την εφαρμογή React σας πιο προσβάσιμη και φτάστε σε νέες αγορές με τη διεθνοποίηση (i18n).

Καθώς ο κόσμος γίνεται όλο και πιο παγκοσμιοποιημένος, γίνεται όλο και πιο σημαντικό για τους προγραμματιστές ιστοσελίδων να δημιουργούν εφαρμογές που μπορούν να εξυπηρετήσουν χρήστες από διαφορετικές χώρες και κουλτούρες. Ένας από τους βασικούς τρόπους για να το επιτύχετε αυτό είναι μέσω της διεθνοποίησης (i18n), η οποία σας επιτρέπει να προσαρμόσετε την εφαρμογή σας σε διαφορετικές γλώσσες, νομίσματα και μορφές ημερομηνίας.

Σε αυτό το άρθρο, θα εξερευνήσουμε πώς να προσθέσετε διεθνοποίηση στην εφαρμογή σας React Next.js, με render από την πλευρά του διακομιστή. TL;DR: Δείτε το πλήρες παράδειγμα εδώ.

Αυτός ο οδηγός είναι για εφαρμογές Next.js που χρησιμοποιούν το App Router.
Αν χρησιμοποιείτε το Pages Router, δείτε αντ’ αυτού αυτόν τον οδηγό.

Βήμα 1: Εγκαταστήστε μια βιβλιοθήκη i18n

Για να υλοποιήσετε την διεθνοποίηση στην εφαρμογή Next.js, θα επιλέξουμε πρώτα μια βιβλιοθήκη i18n. Υπάρχουν αρκετές δημοφιλείς βιβλιοθήκες, συμπεριλαμβανομένης της next-intl. Σε αυτό το παράδειγμα, ωστόσο, θα χρησιμοποιήσουμε την TacoTranslate.

Η TacoTranslate μεταφράζει αυτόματα τις αλυσίδες σας σε οποιαδήποτε γλώσσα χρησιμοποιώντας πρωτοποριακή τεχνητή νοημοσύνη και σας απαλλάσσει από την κουραστική διαχείριση αρχείων JSON.

Ας την εγκαταστήσουμε χρησιμοποιώντας npm στον τερματικό σας:

npm install tacotranslate

Βήμα 2: Δημιουργήστε έναν δωρεάν λογαριασμό στο TacoTranslate

Τώρα που έχετε εγκαταστήσει το module, ήρθε η ώρα να δημιουργήσετε τον λογαριασμό σας στο TacoTranslate, ένα έργο μετάφρασης και τα αντίστοιχα κλειδιά API. Δημιουργήστε έναν λογαριασμό εδώ. Είναι δωρεάν και δεν απαιτείται να προσθέσετε πιστωτική κάρτα.

Μέσα στο περιβάλλον χρήστη της εφαρμογής TacoTranslate, δημιουργήστε ένα έργο και πλοηγηθείτε στην καρτέλα των κλειδιών API. Δημιουργήστε ένα κλειδί read και ένα κλειδί read/write. Θα τα αποθηκεύσουμε ως μεταβλητές περιβάλλοντος. Το κλειδί read είναι αυτό που ονομάζουμε public και το κλειδί read/write είναι secret. Για παράδειγμα, μπορείτε να τα προσθέσετε σε ένα αρχείο .env στη ρίζα του έργου σας.

.env
TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Βεβαιωθείτε ότι ποτέ δεν θα διαρρεύσετε το μυστικό κλειδί API read/write σε περιβάλλοντα παραγωγής στην πλευρά του πελάτη.

Θα προσθέσουμε επίσης δύο ακόμα μεταβλητές περιβάλλοντος: TACOTRANSLATE_DEFAULT_LOCALE και TACOTRANSLATE_ORIGIN.

  • TACOTRANSLATE_DEFAULT_LOCALE: Ο προεπιλεγμένος κωδικός τοπικής ρύθμισης εφεδρείας. Σε αυτό το παράδειγμα, θα τον ορίσουμε σε en για Αγγλικά.
  • TACOTRANSLATE_ORIGIN: Ο «φάκελος» όπου θα αποθηκεύονται οι συμβολοσειρές σας, όπως το URL του ιστότοπού σας. Διαβάστε περισσότερα σχετικά με τα origins εδώ.
.env
TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Βήμα 3: Ρύθμιση του TacoTranslate

Για να ενσωματώσετε το TacoTranslate στην εφαρμογή σας, θα χρειαστεί να δημιουργήσετε έναν client χρησιμοποιώντας τα κλειδιά API που δημιουργήσατε νωρίτερα. Για παράδειγμα, δημιουργήστε ένα αρχείο με όνομα /tacotranslate-client.js.

/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;

Θα ορίσουμε αυτόματα τα TACOTRANSLATE_API_KEY και TACOTRANSLATE_PROJECT_LOCALE σύντομα.

Η δημιουργία του client σε ξεχωριστό αρχείο διευκολύνει την επαναχρησιμοποίησή του αργότερα. getLocales είναι απλώς μια βοηθητική συνάρτηση με ενσωματωμένη διαχείριση σφαλμάτων. Τώρα, δημιούργησε ένα αρχείο με όνομα /app/[locale]/tacotranslate.tsx, όπου θα υλοποιήσουμε τον πάροχο TacoTranslate.

/app/[locale]/tacotranslate.tsx
'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>
	);
}

Σημειώστε το 'use client'; που υποδηλώνει ότι αυτό είναι ένα client component.

Με τον πάροχο συμφραζομένων τώρα έτοιμο προς χρήση, δημιουργήστε ένα αρχείο με όνομα /app/[locale]/layout.tsx, τη ρίζα διάταξης στην εφαρμογή μας. Σημειώστε ότι αυτή η διαδρομή έχει έναν φάκελο που χρησιμοποιεί Dynamic Routes, όπου [locale] είναι η δυναμική παράμετρος.

/app/[locale]/layout.tsx
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>
	);
}

Το πρώτο που πρέπει να σημειωθεί εδώ είναι ότι χρησιμοποιούμε την παράμετρο Dynamic Route [locale] για να αντλήσουμε τις μεταφράσεις για αυτή τη γλώσσα. Επιπλέον, το generateStaticParams διασφαλίζει ότι όλοι οι κωδικοί τοπικών ρυθμίσεων που έχετε ενεργοποιήσει για το έργο σας προ-αποδίδονται.

Τώρα, ας δημιουργήσουμε την πρώτη μας σελίδα! Δημιουργήστε ένα αρχείο με το όνομα /app/[locale]/page.tsx.

/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!" />
	);
}

Σημειώστε τη μεταβλητή revalidate που λέει στο Next.js να ξαναχτίσει τη σελίδα μετά από 60 δευτερόλεπτα και να διατηρεί τις μεταφράσεις σας ενημερωμένες.

Βήμα 4: Υλοποίηση απόδοσης στην πλευρά του διακομιστή

Το TacoTranslate υποστηρίζει server side rendering. Αυτό βελτιώνει σημαντικά την εμπειρία χρήστη, προβάλλοντας άμεσα το μεταφρασμένο περιεχόμενο, αντί για μια στιγμιαία εμφάνιση αμετάφραστου περιεχομένου. Επιπλέον, μπορούμε να παραλείψουμε τα αιτήματα δικτύου από τον πελάτη, επειδή ήδη διαθέτουμε τις μεταφράσεις που χρειαζόμαστε για τη σελίδα που βλέπει ο χρήστης.

Για να ρυθμίσετε το server side rendering, δημιουργήστε ή τροποποιήστε το αρχείο /next.config.js:

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

Τροποποιήστε τον έλεγχο isProduction ώστε να ταιριάζει με τη ρύθμισή σας. Εάν είναι true, το TacoTranslate θα εμφανίσει το δημόσιο κλειδί API. Εάν βρισκόμαστε σε τοπικό, δοκιμαστικό ή περιβάλλον staging (isProduction is false), θα χρησιμοποιήσουμε το μυστικό κλειδί API read/write για να διασφαλίσουμε ότι νέες συμβολοσειρές αποστέλλονται για μετάφραση.

Για να εξασφαλίσουμε ότι η δρομολόγηση και η ανακατεύθυνση λειτουργούν όπως αναμένεται, θα χρειαστεί να δημιουργήσουμε ένα αρχείο με όνομα /middleware.ts. Χρησιμοποιώντας Middleware, μπορούμε να ανακατευθύνουμε τους χρήστες σε σελίδες που παρουσιάζονται στη γλώσσα επιλογής τους.

/middleware.ts
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);
}

Φροντίστε να ρυθμίσετε το matcher σύμφωνα με την Τεκμηρίωση Middleware του Next.js.

Στον πελάτη, μπορείτε να αλλάξετε το locale cookie για να αλλάξετε ποια είναι η προτιμώμενη γλώσσα του χρήστη. Παρακαλούμε δείτε τον πλήρη κώδικα παραδείγματος για ιδέες σχετικά με το πώς να το κάνετε!

Βήμα 5: Αναπτύξτε και δοκιμάστε!

Έχουμε τελειώσει! Η εφαρμογή React σας τώρα θα μεταφράζεται αυτόματα όταν προσθέτετε οποιεσδήποτε συμβολοσειρές σε ένα Translate component. Σημειώστε ότι μόνο τα περιβάλλοντα με δικαιώματα read/write στο API key θα μπορούν να δημιουργούν νέες συμβολοσειρές προς μετάφραση. Σας προτείνουμε να έχετε ένα κλειστό και ασφαλές περιβάλλον staging όπου μπορείτε να δοκιμάζετε την παραγωγική σας εφαρμογή με ένα τέτοιο API key, προσθέτοντας νέες συμβολοσειρές πριν την επίσημη δημοσίευση. Αυτό θα αποτρέψει οποιονδήποτε από το να κλέψει το κρυφό σας API key και πιθανώς να φουσκώσει το project μετάφρασής σας με νέες, άσχετες συμβολοσειρές.

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!

Ένα προϊόν από NattskiftetΚατασκευάστηκε στη Νορβηγία