Astro + React Sitenizi Intlayer ile Çevirin | Uluslararasılaştırma (i18n)

İçindekiler

Intlayer Nedir?

Intlayer, modern web uygulamalarında çok dilli desteği basitleştirmek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma (i18n) kütüphanesidir.

Intlayer ile şunları yapabilirsiniz:

• Çevirileri kolayca yönetin: Bileşen düzeyinde deklaratif sözlükler kullanarak.
• Meta verileri, rotaları ve içeriği dinamik olarak yerelleştirin.
• TypeScript desteği sağlayın: Daha iyi otomatik tamamlama ve hata algılama için otomatik olarak oluşturulan türlerle.
• Gelişmiş özelliklerden yararlanın: Dinamik dil algılama ve değiştirme gibi.

Astro + React'te Intlayer'ı Yapılandırmak İçin Adım Adım Kılavuz

GitHub'daki uygulama şablonuna göz atın.

Adım 1: Bağımlılıkları Yükleyin

Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri yükleyin:

npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/reactnpx intlayer init

• intlayer Konfigürasyon yönetimi, çeviriler, içerik deklarasyonu, transpilasyon ve CLI komutları için i18n araçları sağlayan temel paket.

• astro-intlayer Intlayer'ı Vite paketleyici ile bağlamak için Astro entegrasyon eklentisi; ayrıca kullanıcının tercih ettiği dili algılamak, çerezleri yönetmek ve URL yönlendirmelerini işlemek için ara yazılım (middleware) içerir.

• react, react-dom React bileşenlerini tarayıcıda oluşturmak için kullanılan temel React paketleri.

• react-intlayer Intlayer'ı React uygulamalarına entegre etmek için paket. React'te uluslararasılaştırma için IntlayerProvider'ın yanı sıra useIntlayer ve useLocale hook'larını sağlar.

• @astrojs/react React bileşen islands kullanımına olanak tanıyan resmi Astro entegrasyonu.

Adım 2: Projenizi Yapılandırın

Uygulamanızın dillerini tanımlamak için bir konfigürasyon dosyası oluşturun:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.TURKISH,      // Diğer dilleriniz    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Bu konfigürasyon dosyası aracılığıyla yerelleştirilmiş URL'leri, ara yazılım yönlendirmelerini, çerez adlarını, içerik deklarasyonlarının konumunu ve uzantılarını yapılandırabilir, konsoldaki Intlayer günlüklerini devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Kullanılabilir parametrelerin tam listesi için konfigürasyon dokümantasyonuna bakın.

Adım 3: Intlayer'ı Astro konfigürasyonunuza entegre edin

Astro konfigürasyonunuza intlayer eklentisini ve React entegrasyonunu ekleyin.

// @ts-checkimport { intlayer } from "astro-intlayer";import react from "@astrojs/react";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), react()],});

intlayer() entegrasyon eklentisi, Intlayer'ı Astro ile entegre etmek için kullanılır. İçerik deklarasyon dosyalarının oluşturulmasını sağlar ve bunları geliştirme modunda izler. Astro uygulaması içinde Intlayer ortam değişkenlerini tanımlar ve performansı optimize etmek için takma adalar (aliases) sağlar.

react() entegrasyonu, client:only="react" aracılığıyla React bileşen islands kullanımına olanak tanır.

Adım 4: İçeriğinizi Deklare Edin

Çevirileri saklamak için içerik deklarasyonlarınızı oluşturun ve yönetin:

import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      tr: "Merhaba Dünya",    }),  },} satisfies Dictionary;export default appContent;

İçerik deklarasyonları, contentDir (varsayılan olarak ./src) içinde yer aldıkları ve içerik deklarasyon dosyası uzantısıyla (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs}) eşleştikleri sürece uygulamanızın herhangi bir yerinde tanımlanabilir.

Daha fazla bilgi için içerik deklarasyon dokümantasyonuna bakın.

Adım 5: Astro'da İçerik Kullanma

Sözlükleri doğrudan .astro dosyalarınızda, intlayer'dan dışa aktarılan temel yardımcıları kullanarak tüketebilirsiniz. Her sayfaya SEO meta verileri (hreflang ve kurallı bağlantılar gibi) eklemeli ve etkileşimli istemci tarafı içeriği için bir React island tanıtmalısınız.

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";import { ReactIsland } from "../../components/react/ReactIsland";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <!-- Kurallı (Canonical) Bağlantı: Arama motorlarını bu sayfanın ana sürümü hakkında bilgilendirir -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Google'ı tüm yerelleştirilmiş sürümler hakkında bilgilendirir -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Dil kullanıcının diliyle eşleşmediğinde kullanılan geri dönüş (fallback) seçeneği -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- React island, dil seçici de dahil olmak üzere tüm etkileşimli içeriği oluşturur -->    <ReactIsland locale={locale} client:only="react" />  </body></html>

Yönlendirme Kurulumu Hakkında Not: Kullandığınız dizin yapısı, intlayer.config.ts dosyasındaki middleware.routing ayarına bağlıdır:

• prefix-no-default (varsayılan): Varsayılan dili kök dizinde tutar (önek yok) ve diğerlerine önek ekler. Tüm durumları yakalamak için [...locale] kullanın.
• prefix-all: Tüm URL'ler bir dil öneki alır. Kök dizini ayrı işlemek gerekmiyorsa standart [locale] kullanabilirsiniz.
• search-param veya no-prefix: Dil dizinlerine gerek yoktur. Dil, sorgu parametreleri veya çerezler aracılığıyla yönetilir.

Adım 6: Bir React Island Bileşeni Oluşturun

React uygulamanızı sarmalayan ve sunucu tarafından algılanan dili alan bir island bileşeni oluşturun:

/** @jsxImportSource react */import { IntlayerProvider, useIntlayer } from "react-intlayer";import { type LocalesValues } from "intlayer";import { LocaleSwitcher } from "./LocaleSwitcher";function App() {  const { title } = useIntlayer("app");  return (    <div>      <h1>{title}</h1>      <LocaleSwitcher />    </div>  );}export function ReactIsland({ locale }: { locale: LocalesValues }) {  return (    <IntlayerProvider locale={locale}>      <App />    </IntlayerProvider>  );}

locale prop'u, Astro sayfasından (sunucu algılaması) IntlayerProvider'a aktarılır ve ağaç içindeki tüm React hook'ları için başlangıç dili olarak hizmet eder.

Adım 7: Bir Dil Seçici Ekleme

Kullanılabilir dilleri okuyan ve kullanıcı yeni bir dil seçtiğinde yerelleştirilmiş URL'ye yönlendiren bir React LocaleSwitcher bileşeni oluşturun:

/** @jsxImportSource react */import { useLocale } from "react-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";export function LocaleSwitcher() {  const { locale, availableLocales, setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      // Dil değişikliğinde yerelleştirilmiş URL'ye yönlendir      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  return (    <div className="locale-switcher">      <span className="switcher-label">Dili değiştir:</span>      <div className="locale-buttons">        {availableLocales.map((localeItem) => (          <button            key={localeItem}            onClick={() => setLocale(localeItem)}            className={`locale-btn ${localeItem === locale ? "active" : ""}`}            disabled={localeItem === locale}          >            <span className="ls-own-name">{getLocaleName(localeItem)}</span>            <span className="ls-current-name">              {getLocaleName(localeItem, locale)}            </span>            <span class="ls-code">{localeItem.toUpperCase()}</span>          </button>        ))}      </div>    </div>  );}

Kalıcılık Hakkında Not: window.location.href aracılığıyla yönlendirmek için onLocaleChange kullanmak, yeni dil URL'sinin ziyaret edilmesini sağlar. Bu da Intlayer ara yazılımının dil çerezini ayarlamasına ve gelecekteki ziyaretlerde kullanıcının tercihini hatırlamasına olanak tanır.

LocaleSwitcher, IntlayerProvider içinde oluşturulmalıdır - bunu island bileşeninizde kullanın (Adım 6'da gösterildiği gibi).

Adım 8: Sitemap ve Robots.txt

Intlayer, yerelleştirilmiş site haritanızı ve robots.txt dosyalarınızı dinamik olarak oluşturmak için yardımcı programlar sunar.

Sitemap

Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

Tüm yerelleştirilmiş rotalarınızı içeren bir site haritası oluşturmak için src/pages/sitemap.xml.ts dosyasını oluşturun.

import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

Robots.txt

Arama motoru taramasını kontroll etmek için src/pages/robots.txt.ts dosyasını oluşturun.

import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

TypeScript Yapılandırması

Intlayer, kod tabanınızı daha sağlam hale getirmek için TypeScript'ten yararlanmak amacıyla modül artırımı (module augmentation) kullanır.

TypeScript yapılandırmanızın otomatik olarak oluşturulan türleri içerdiğinden emin olun.

{  // ... mevcut TypeScript yapılandırmanız  "include": [    // ... mevcut TypeScript yapılandırmanız    ".intlayer/**/*.ts", // Otomatik oluşturulan türleri dahil edin  ],}

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların yoksayılması önerilir. Bu, onları Git deponuza göndermenizi engeller.

Bunu yapmak için .gitignore dosyanıza aşağıdaki talimatları ekleyin:

# Intlayer tarafından oluşturulan dosyaları yoksay.intlayer

İçeriğinizi alt, title, href, aria-label vb. gibi bir dize (string) özniteliğinde kullanmak istiyorsanız, işlevin değerini şu şekilde kullanabilirsiniz:

html

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

VS Code Uzantısı

Intlayer ile geliştirme deneyiminizi iyileştirmek için resmi Intlayer VS Code uzantısını yükleyebilirsiniz.

VS Code Marketplace'ten Kurulum

Bu uzantı şunları sağlar:

• Çeviri anahtarları için otomatik tamamlama.
• Eksik çeviriler için gerçek zamanlı hata algılama.
• Çevrilmiş içeriğin satır içi önizlemesi.
• Kolayca çeviri oluşturmak ve güncellemek için hızlı eylemler.

Uzantı kullanımı hakkında daha fazla bilgi için VS Code Uzantısı dokümantasyonuna bakın.

(İsteğe bağlı) Adım 17 : Bileşenlerinizin içeriğini çıkarın

Mevcut bir kod tabanınız varsa, binlerce dosyayı dönüştürmek zaman alıcı olabilir.

Bu süreci kolaylaştırmak için Intlayer, bileşenlerinizi dönüştürmek ve içeriği çıkarmak için bir derleyici / çıkarıcı sunar.

Kurulum için intlayer.config.ts dosyanıza bir compiler bölümü ekleyebilirsiniz:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Yapılandırmanızın geri kalanı
  compiler: {
    /**
     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.
     */
    enabled: true,

    /**
     * Çıktı dosyalarının yolunu tanımlar
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Bileşenlerin dönüştürüldükten sonra kaydedilip kaydedilmeyeceğini belirtir. Bu sayede derleyici, uygulamayı dönüştürmek için yalnızca bir kez çalıştırılabilir ve ardından kaldırılabilir.
     */
    saveComponents: false,

    /**
     * Sözlük anahtarı öneki
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Derleyici eklentisini ekler ],});

npm run build # Veya npm run dev

Bilginizi Derinleştirin

Daha fazlasını öğrenmek isterseniz, içeriğinizi dış kaynaklara aktarmak için Görsel Editör'ü uygulayabilir veya CMS kullanabilirsiniz.