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ştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılar için uygulamalar geliştirmeleri giderek daha önemli hale geliyor. Bunu başarmanın temel yollarından biri uluslararasılaştırmadır (i18n), bu sayede uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlayabilirsiniz.

Bu eğitimde, React Next.js uygulamanıza sunucu tarafı rendering ile nasıl uluslararasılaştırma ekleyeceğimizi inceleyeceğiz. TL;DR: Tam örneği burada görün.

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

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çeceğiz. next-intl dahil olmak üzere birkaç popüler kütüphane vardır. Ancak, bu örnekte TacoTranslate kullanacağız.

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

Bunu terminalinizde npm kullanarak yükleyelim:

npm install tacotranslate

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

Modülü kurduğunuza göre, şimdi TacoTranslate hesabınızı, bir çeviri projesi ve ilgili API anahtarlarını oluşturmanın zamanı geldi. 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ı ortam değişkeni olarak kaydedeceğiz. read anahtarı bizim public dediğimiz anahtardır ve read/write anahtarı ise secret olarak adlandırılır. Örneğin, bunları projenizin kök dizininde bulunan .env dosyasına ekleyebilirsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API anahtarını asla istemci tarafı üretim ortamlarına sızdırmadığınızdan 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: Metinlerinizin saklanacağı “klasör”, örneğin web sitenizin URL'si. Kökenler hakkında daha fazla bilgi için burayı okuyun.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate'i uygulamanıza entegre etmek için, ö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.

İ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ınız varsa, yukarıdaki özellikler ve kod ile tanımı genişletiniz.

Adım 4: Sunucu tarafı render işlemini uygulama

TacoTranslate, çevirilerinizin sunucu tarafı render edilmesine olanak tanır. Bu, kullanıcı deneyimini, önce çevrilmemiş içeriğin kısa bir süre gösterilmesi yerine, çevrilmiş içeriğin hemen gösterilmesiyle büyük ölçüde iyileştirir. Ayrıca, ihtiyacımız olan tüm çeviriler elimizde olduğu için istemcideki ağ isteklerini atlayabiliriz.

Başlangıç olarak /next.config.js dosyasını oluşturacak 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ı yalnızca desteklenen diller listesi ile ayarladık. Sonraki yapacağımız şey, tüm sayfalarınız için çevirileri almak olacak. Bunu yapmak için, gereksinimlerinize bağlı olarak getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanacaksınız.

Bu fonksiyonlar üç argüman alır: Bir Next.js Static Props Context nesnesi, TacoTranslate için yapılandırma 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.

Bu fonksiyonlardan birini bir sayfada kullanmak için, diyelim ki /pages/hello-world.tsx gibi bir sayfa dosyanız var.

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ınlayın ve test edin!

İşlem tamam! Artık Next.js uygulamanızda 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. Üretim uygulamanızı böyle bir API anahtarı ile test edebileceğiniz kapalı ve güvenli bir staging ortamı oluşturmanızı öneriyoruz; böylece yayına almadan önce yeni metinler ekleyebilirsiniz. Bu, gizli API anahtarınızın çalınmasını önleyecek ve çeviri projenizin gereksiz, alakasız metinlerle ş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!