Next.js uygulamalarında uluslararasılaştırma (i18n) için en iyi çözüm

Nasıl çalışır

Dünya daha da küreselleştikçe, web geliştiricilerin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın temel yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n) yöntemidir.

Bu eğitimde, React Next.js uygulamanıza sunucu tarafı render ile uluslararasılaştırmayı nasıl ekleyeceğimizi keşfedeceğiz. TL;DR: Tam örneği buradan görebilirsiniz.

Bu rehber, Pages Router kullanan Next.js uygulamaları içindir.
Eğer App Router kullanıyorsanız, lütfen bunun yerine bu rehbere bakın.

Adım 1: Bir i18n kütüphanesi yükleyin

Next.js uygulamanızda uluslararasılaştırmayı uygulamak için önce bir i18n kütüphanesi seçelim. next-intl gibi birkaç popüler kütüphane vardır. Ancak, bu örnekte TacoTranslate kullanacağız.

TacoTranslate, ileri teknolojili yapay zeka kullanarak dizelerinizi otomatik olarak istediğiniz dile çevirir ve JSON dosyalarının zahmetli yönetiminden sizi kurtarır.

Terminalinizde npm kullanarak kurulum yapalım:

npm install tacotranslate

Adım 2: Ücretsiz bir TacoTranslate hesabı oluşturun

Modülü yüklediğinize göre, şimdi TacoTranslate hesabınızı, bir çeviri projesi ve ilgili API anahtarlarını oluşturma zamanı. Buradan hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulama arayüzünde bir proje oluşturun ve API anahtarları sekmesine gidin. Bir tane read anahtarı ve bir tane read/write anahtarı oluşturun. Bunları ortam değişkenleri olarak kaydedeceğiz. read anahtarına public adını veriyoruz ve read/write anahtarı ise secret olarak adlandırılır. Örneğin, bunları projenizin kök dizinindeki .env dosyasına ekleyebilirsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API anahtarının istemci tarafı üretim ortamlarına asla sızdırılmadığından emin olun.

Ayrıca iki tane daha ortam değişkeni ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek dil kodu. Bu örnekte, İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Dizelerinizin depolanacağı “klasör”, örneğin web sitenizin URL’si. Originler hakkında daha fazla bilgi için buraya tıklayın.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate'ı uygulamanıza entegre etmek için, daha önceki API anahtarlarını kullanarak bir istemci oluşturmanız gerekecek. Örneğin, /tacotranslate-client.js adlı bir dosya oluşturun.

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;

Kısa süre içinde TACOTRANSLATE_API_KEY otomatik olarak tanımlanacaktır.

Müşteriyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. Şimdi, özel bir /pages/_app.tsx kullanarak TacoTranslate sağlayıcısını ekleyeceğiz.

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

Eğer zaten özel pageProps ve _app.tsx dosyalarınız varsa, tanımı yukarıdaki özellikler ve kod ile genişletin lütfen.

Adım 4: Sunucu tarafı render işleminin uygulanması

TacoTranslate, çevirilerinizin sunucu tarafı render edilmesine olanak tanır. Bu, kullanıcı deneyimini önemli ölçüde geliştirir; çünkü önce çevrilmemiş içerik yerine çevrilmiş içeriği hemen gösterir. Ayrıca, ihtiyaç duyduğumuz tüm çevirilere zaten sahip olduğumuz için istemcide ağ isteklerini atlayabiliriz.

Başlangıç olarak /next.config.js dosyasını oluşturacağız veya değiştireceğiz.

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

isProduction kontrolünü kurulumunuza uyacak şekilde değiştirin. trueise, TacoTranslate genel API anahtarını ortaya çıkaracaktır. Yerel, test veya hazırlama ortamındaysak (isProduction is false), yeni dizgilerin çeviri için gönderildiğinden emin olmak için gizli read/write API anahtarını kullanacağız.

Şimdiye kadar, Next.js uygulamasını sadece desteklenen diller listesiyle kurduk. Sonraki adım, tüm sayfalarınız için çevirileri almaktır. Bunu yapmak için, ihtiyaçlarınıza bağlı olarak getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanılacaktır.

Bu fonksiyonlar üç argüman alır: Bir Next.js Static Props Context nesnesi, TacoTranslate yapılandırması ve isteğe bağlı Next.js özellikleri. getTacoTranslateStaticProps üzerindeki revalidate varsayılan olarak 60 olarak ayarlanmıştır, böylece çevirileriniz güncel kalır.

Her iki fonksiyonu bir sayfada kullanmak için, elinizde /pages/hello-world.tsx gibi bir sayfa dosyası olduğunu varsayalım.

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

Artık tüm React bileşenlerinizdeki metinleri çevirmek için Translate bileşenini kullanabilmelisiniz.

import {Translate} from 'tacotranslate/react';

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

Adım 5: Dağıt ve test et!

İşlem tamam! Next.js uygulamanız artık herhangi bir ifadeyi Translate bileşenine eklediğinizde otomatik olarak çevrilecek. Dikkat edin, yalnızca API anahtarında read/write izinlerine sahip ortamlar yeni çevrilecek ifadeler oluşturabilir. Üretim uygulamanızı böyle bir API anahtarı ile test edebileceğiniz kapalı ve güvenli bir staging ortamına sahip olmanızı öneririz; yeni ifadeleri canlıya almadan önce ekleyebilirsiniz. Bu, gizli API anahtarınızın çalınmasını ve çeviri projenizin alakasız yeni ifadelerle şişirilmesini önleyecektir.

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!