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 kullanıcıları karşılayabilecek uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın ana yollarından biri ise, 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 inceleyin.

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

Adım 1: Bir i18n kütüphanesi kurun

Next.js uygulamanızda uluslararasılaştırmayı uygulamak için önce bir i18n kütüphanesi seçeceğiz. Birkaç popüler kütüphane bulunmaktadır, bunlar arasında next-intl da var. Ancak, bu örnekte TacoTranslate kullanacağız.

TacoTranslate, en son yapay zeka teknolojisi kullanarak dizelerinizi otomatik olarak herhangi bir dile çevirir ve sizi JSON dosyalarının zahmetli yönetiminden kurtarır.

Terminalinizde npm kullanarak yükleyelim:

npm install tacotranslate

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

Modülü kurduğunuza göre, artık TacoTranslate hesabınızı, bir çeviri projesi oluşturma ve ilişkili API anahtarlarını oluşturma zamanı. Buradan bir 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ı çevresel değişkenler olarak kaydedeceğiz. read anahtarı, public olarak adlandırdığımız anahtardır ve read/write anahtarı ise secret anahtarıdı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ı kesinlikle istemci tarafı üretim ortamlarına sızdırmayın.

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, en olarak İngilizce'yi ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Dizgilerinizin saklanacağı "klasör", örneğin web sitenizin URL'si. Burada originler hakkında daha fazla bilgi edinin.

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 bir süre içinde TACOTRANSLATE_API_KEY otomatik olarak tanımlanacaktır.

İstemciyi 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ına sahipseniz, yukarıdaki özellikler ve kod ile tanımı genişletin lütfen.

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

TacoTranslate, çevirilerinizin sunucu tarafında render edilmesine olanak tanır. Bu, kullanıcı deneyimini önemli ölçüde iyileştirir çünkü önce çevrilmemiş içeriğin bir anlık görüntüsü yerine çevirilmiş içeriği hemen gösterir. Ayrıca, tüm gerekli çevirilere zaten sahip olduğumuz için istemci tarafında ağ isteklerini atlayabiliriz.

İşe /next.config.js dosyasını oluşturarak veya değiştirerek başlayacağız.

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: Yayınla ve test et!

İşlem tamam! Artık Next.js uygulamanız, herhangi bir metni Translate bileşenine eklediğinizde otomatik olarak çevrilecektir. API anahtarında read/write izinlerine sahip olan ortamların yeni çevrilecek metinler oluşturabileceğini unutmayın. Canlıya geçmeden önce yeni metinler ekleyebileceğiniz, kapalı ve güvenli bir staging ortamına sahip olmanızı tavsiye ederiz. Bu, gizli API anahtarınızın çalınmasını önleyecek ve çeviri projenizin yeni, alakasız metinlerle gereksiz yere şişmesini engelleyecektir.

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!