በ App Router የሚጠቀም Next.js መተግበሪያ ውስጥ የዓለም አቀፍ ቋንቋ ማስተካከያን እንዴት ማስፈፀም

ዓለም ሲዋቀር እና እየተጋለጠ ሲሆን፣ ለተለያዩ ሀገራትና ባህላት የሚመጡ ተጠቃሚዎችን ሊያገለግሉ የሚችሉ መተግበሪያዎችን ለመገንባት ለድር አባላት እየተጨማረ አስፈላጊ ነው። ይህን ለማሳካት ከዋና ዘዴዎች አንዱ ኢንተርናሽናሊዜሽን (i18n) ሲሆን፣ ይህ መተግበሪያዎን ወደ ተለያዩ ቋንቋዎች፣ የገንዘብ አይነቶች እና የቀን ቅርጾች ለማስተካከል ይፈቅዳል።

በዚህ ጽሑፍ ውስጥ፣ ከሰርቨር ጋር የሚሰራ የReact Next.js መተግበሪያዎችን በኢንተርናሽናሊዜሽን እንዴት እንደምንጨምር እንረዳለን። TL;DR: ሙሉውን ምሳሌ እዚህ ይመልከቱ.

ይህ መመሪያ ለ እዚህ የ App Router እንደሚጠቀሙ የ Next.js መተግበሪያዎች ነው.
ከ Pages Router ብትጠቀሙ፣ ይህን መመሪያ ይመልከቱ።

እርምጃ 1: i18n ላይብራሪን ያጫኑ

በNext.js መተግበሪያዎ ውስጥ የአለም ቋንቋ ማስተርጎም (internationalization) ለማስፈፀም በመጀመሪያ አንድ i18n ላይብራሪ እንምረጥ። ብዙ የተለመዱ ላይብራሪዎች አሉ፣ ከነዚህም next-intl አንዱ ነው። ነገር ግን በዚህ ምሳሌ እኛ TacoTranslate እንጠቀማለን።

TacoTranslate በዘመናዊ አርቲፊሻል ኢንተሊጅንስ (AI) የሚሰራ ሲሆን የየጽሑፎችዎን (strings) ወደ ማንኛውም ቋንቋ በራሱ ይተርጉማል፣ እና ከJSON ፋይሎችን የሚከተለውን ዋጋያዊ እና ተወላጅ አስተዳደር ከእርስዎ ይወስዳል።

በተርሚናልዎ ውስጥ በnpm መጠቀም እንጫነዋለን:

npm install tacotranslate

ደረጃ 2: ነፃ የTacoTranslate መለያ ይፍጠሩ

አሁን ሞጁሉን ካጫኑ በኋላ፣ የTacoTranslate መለያዎን፣ የትርጉም ፕሮጀክትን እና ተዛማጅ የAPI ቁልፎችን ለመፍጠር ጊዜው ነው። እዚህ መለያ ይፍጠሩ። ነጻ ነው፤ እና የክሬዲት ካርድ መጨመር አያስፈልግም።

የTacoTranslate አፕሊኬሽን UI ውስጥ ፕሮጀክት ፍጠሩ፣ እና ወደ የAPI ቁልፎች ታብ ይሂዱ። አንድ read ቁልፍ እና አንድ read/write ቁልፍ ይፍጠሩ። እነዚህን እንደ environment variables እንቀርባለን። የ read ቁልፍ የምንጠራው public ሲሆን የ read/write ቁልፍ ግን secret ነው። ለምሳሌ፣ እነዚህን በፕሮጀክትዎ ራስ (root) ውስጥ ያለ .env ፋይል ማካተት ይችላሉ።

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

እርግጠኛ ይሁኑ ምንም ሁኔታ ሆነ ምስጢሩን read/write የAPI ቁልፍ ወደ ክላይንት-ሳይድ ፕሮዳክሽን አካባቢዎች አታስወጡ።

እንዲሁም ሌሎች ሁለት የአካባቢ ተለዋዋጮችን እንጨምራለን: TACOTRANSLATE_DEFAULT_LOCALE እና TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: የመጠናቀቂያ የቋንቋ ኮድ። በዚህ ምሳሌ፣ ለእንግሊዝኛ እንደ en እንቀመጣለን።
• TACOTRANSLATE_ORIGIN: የጽሑፎችዎ የሚያስቀምጡበት “ፎልደር”፣ ለምሳሌ የድር ጣቢያዎ ዩአርኤል። ስለ መነሻዎች በተጨማሪ እዚህ ያነቡ።

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

እርምጃ 3: የTacoTranslate ማቋቋም

TacoTranslateን ከመተግበሪያዎ ጋር ለመካተት፣ ከዚህ ቀደም ያሉትን 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 በአውቶሜቲክ ሁኔታ በቅርብ ጊዜ እንወስናለን።

ደንበኛውን በተለየ ፋይል ላይ ማፍጠር ከዚያ ቀጥሎ ለመጠቀም ቀላል ያደርጋል። getLocales የተጠቀሰው ውስጥ የስህተት አስተዳደር ያለው አንድ አጠቃቀም (utility) ፋንክሽን ብቻ ነው። አሁን፣ /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 አቅራቢው አሁን ዝግጁ ሲሆን፣ የመተግበሪያችን ዋና ቅርጸ ቅርጽ ለማቋቋም /app/[locale]/layout.tsx በዚያ ስም ፋይል ይፍጠሩ። ይህ መንገድ በ 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 ለፕሮጀክትዎ ውስጥ ያሉትን ሁሉንም የlocale ኮዶች ቀድሜ እንዲቀድሙ ያረጋግጣል።

አሁን፣ የመጀመሪያችንን ገፅ እንገነባለን! ስሙ ያለውን ፋይል /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) ይደግፋል። ይህ ትርጉም ያለውን ይዘት በአቅፊ በቀጥታ ማሳየት ይችላል፣ እንግዲህ ከመጀመሪያ የማይተረጉም ይዘት የሚባለው የፍላሽ ስርዓት እንዳይኖር ይረዳል። በተጨማሪም፣ ለተጠቃሚው የሚታየው ገፅ የሚያስፈልጉትን ትርጉሞች እንዳለን ስለሆነ በክላይንት ላይ የኔትወርክ ጥያቄዎችን መላክን ማስወገድ እንችላለን።

የሰርቨር ላይ የሚከናወን አቀራረብ ለማቋቋም, /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 ቁልፍን ያሳያል። በ local, test ወይም staging አካባቢ (isProduction is false) ከሆንን፣ አዲስ ሀረጎች ለትርጉም እንዲልኩ ለማረጋገጥ ምስጥራዊ read/write API ቁልፍን እንጠቀማለን።

የመንገድ እና ዳግም መላለስ ሂደቶች እንደተጠበቀ እንዲሰሩ ለማረጋገጥ, /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 ሰነድ ጋር በተዛመደ መልኩ ያቀናብሩ።

በክላይንት ላይ፣ የlocale cookie በመቀየር የተጠቃሚው የሚመረጠውን ቋንቋ ማቀየር ይችላሉ። ይህን እንዴት እንደሚደረግ ለማወቅ እባክዎን ሙሉ የምሳሌ ኮድ ይመልከቱ!

እርምጃ 5: አቅርቡ እና ይፈትሹ!

እኛ ስራውን ጨርሰናል! የReact መተግበሪያዎ ከእርስዎ ወደ Translate ኮምፖነንት ማንኛውንም የጽሑፍ ቃላት ሲጨምሩ በራሱ በራስ ይተርጉማል። ማሳሰቢያ፥ በAPI ቁልፉ ላይ read/write ፈቃድ ያላቸው አካባቢዎች ብቻ የሚተርጉሙ አዲስ የጽሑፍ ቃላትን ማፍጠር ይችላሉ። በእኛ ምክር፣ እንደዚህ ዓይነት የAPI ቁልፍ በመጠቀም የፕሮዳክሽን መተግበሪያዎን ለማሞከር የተዘጋና ደህንነታዊ የሙከራ (staging) አካባቢ እንዳለዎት መኖሩን እንጠይቃለን፣ እዚህ በማሞከር ከመለቀቅ/ከማስጀመር በፊት አዲስ የጽሑፍ ቃላትን ማስገባት ይችላሉ። ይህ የሚስጥር 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!