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

Nasıl çalışır

Dünya daha küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın ana 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ırmanın nasıl ekleneceğini keşfedeceğiz. TL;DR: Tam örneği buradan görebilirsiniz.

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.

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

Next.js uygulamanızda uluslararasılaştırmayı (i18n) uygulamak için önce bir i18n kütüphanesi seçeceğiz. next-intl dahil olmak üzere birkaç popüler kütüphane bulunmaktadır. Ancak, bu örnekte TacoTranslate kullanacağız.

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

Terminalinizde npm kullanarak yükleyelim:

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ı eklemeniz gerekmez.

TacoTranslate uygulama arayüzü içinde 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ı bizim public olarak adlandırdığımız anahtar olup, read/write anahtarı ise secret olan anahtardı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ı asla istemci tarafı üretim ortamlarına sızdırmadığınızdan emin olun.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan geri dönüş yerel 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 edinin.

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

Adım 3: TacoTranslate Kurulumu

TacoTranslate'i uygulamanızla entegre etmek için, daha önceki API anahtarlarını kullanarak bir istemci oluşturmanız gerekir. Örneğin, /tacotranslate-client.jsadlı 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;

TACOTRANSLATE_API_KEY kısa süre içinde 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, lütfen tanımı yukarıdaki özellikler ve kod ile genişletin.

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

TacoTranslate, çevirilerinizin sunucu tarafında render edilmesini sağlar. Bu, çevrilmemiş içeriğin önce kısa bir süre görünmesi yerine, çevrilmiş içeriğin hemen gösterilmesiyle kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, gerekli tüm ç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 listesi ile kurduk. Şimdi yapacağımız şey, tüm sayfalarınız için çevirileri getirmek olacak. Bunu yapmak için, ihtiyaçlarınıza bağlı olarak getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanacaksınız.

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’a ayarlanmıştır, böylece çevirileriniz güncel kalır.

Her iki fonksiyonu bir sayfada kullanmak için, örneğin /pages/hello-world.tsx gibi bir sayfa dosyanız 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ızda Translate bileşenine herhangi bir metin eklediğinizde otomatik olarak çeviri yapılacaktır. API anahtarında read/write izinlerine sahip olan ortamların yeni çevrilecek metinler oluşturabileceğini unutmayın. Üretim uygulamanızı canlıya almadan önce yeni metinler ekleyerek test edebileceğiniz kapalı ve güvenli bir staging ortamı kullanmanızı öneririz. Bu, gizli API anahtarınızın çalınmasını önleyecek ve çeviri projenizin alakasız yeni metinlerle şişmesini engelleyecektir.

GitHub profilimizde tam örneğe göz atmayı unutmayın. Orada ayrıca App Router kullanarak bunu nasıl yapacağınıza dair bir örnek de bulacaksınız! Herhangi bir sorunla karşılaşırsanız, lütfen iletişime geçmekten çekinmeyin, size yardımcı olmaktan memnuniyet duyarız.

TacoTranslate, React uygulamalarınızı herhangi bir dilde hızlıca otomatik olarak yerelleştirmenizi sağlar. Hemen başlayın!