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

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

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

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

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

Για να υλοποιήσετε τη διεθνοποίηση (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 στη ρίζα του έργου σας.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

• TACOTRANSLATE_DEFAULT_LOCALE: Ο προεπιλεγμένος κωδικός τοπικής ρύθμισης (fallback). Στο παράδειγμα αυτό, θα το ορίσουμε σε en για Αγγλικά.
• TACOTRANSLATE_ORIGIN: Ο "φάκελος" όπου θα αποθηκεύονται οι συμβολοσειρές σας, όπως η διεύθυνση URL του ιστότοπού σας. Διαβάστε περισσότερα σχετικά με τις προελεύσεις εδώ.

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

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

Για να ενσωματώσετε το TacoTranslate στην εφαρμογή σας, θα χρειαστεί να δημιουργήσετε έναν client χρησιμοποιώντας τα κλειδιά API από πριν. Για παράδειγμα, δημιουργήστε ένα αρχείο με όνομα /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.

'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'; που υποδεικνύει ότι πρόκειται για ένα συστατικό πελάτη.

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

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.

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: Υλοποίηση rendering από την πλευρά του διακομιστή

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

Για να ρυθμίσετε την απόδοση από την πλευρά του διακομιστή, δημιουργήστε ή τροποποιήστε /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, μπορούμε να ανακατευθύνουμε τους χρήστες σε σελίδες που εμφανίζονται στην προτιμώμενη γλώσσα τους.

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 σύμφωνα με την τεκμηρίωση του Next.js για το Middleware.

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

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

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

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!