Yazar:
    Oluşturma:2024-03-07Son güncelleme:2026-06-23

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

    ide.intlayer.org

    İçindekiler

    Neden alternatifler yerine Intlayer?

    'astro-i18n' veya 'i18next' gibi ana çözümlerle karşılaştırıldığında Intlayer, aşağıdaki gibi entegre optimizasyonlarla gelen bir çözümdür:

    Intlayer, çok dilli yönlendirme, site haritası ve uluslararasılaştırmayı (i18n) ölçeklendirmek için gereken tüm özellikleri sunarak Astro ile mükemmel çalışacak şekilde optimize edilmiştir.

    Sayfalarınıza çok büyük JSON dosyaları yüklemek yerine yalnızca gerekli içeriği yükleyin. Intlayer bundle ve sayfa boyutlarınızı %50'ye kadar azaltmanıza yardımcı olur.

    Uygulamanızın içeriğinin kapsamını belirlemek, büyük ölçekli uygulamalar için bakımı kolaylaştırır. İçerik kod tabanınızın tamamını gözden geçirmenin zihinsel yükü olmadan, tek bir özellik klasörünü çoğaltabilir veya silebilirsiniz. Ayrıca Intlayer, içeriğinizin doğruluğunu sağlamak için tamamen tiplendirilmiş (fully typed)tır.

    İçeriğin bir arada konumlandırılması Büyük Dil Modellerinin (LLM'ler) ihtiyaç duyduğu bağlamı azaltır. Intlayer ayrıca eksik çevirileri test etmek için CLI gibi bir araç paketiyle birlikte gelirLSP, MCP ve aracı becerileri, geliştirici deneyimini (DX) yapay zeka için daha da sorunsuz hale getirmek için ajanlar.

    Maliyeti AI sağlayıcınıza ait olmak üzere seçtiğiniz LLM'yi kullanarak CI/CD işlem hattınızda çeviri yapmak için otomasyonu kullanın. Intlayer ayrıca içerik çıkarmayı otomatikleştirmek için bir derleyici ve arka planda çeviri yapmaya yardımcı olacak bir web platformu sunar.

    Büyük JSON dosyalarını bileşenlere bağlamak performans ve tepkime sorunlarına yol açabilir. Intlayer, içerik yüklemenizi derleme sırasında optimize eder.

    Bir i18n çözümünden çok daha fazlası olan Intlayer, kendi kendine barındırılan bir görsel düzenleyici ve tam CMS çok dilli içeriğinizi gerçek zamanlı olarak yönetmenize yardımcı olarak çevirmenler, metin yazarları ve diğer ekip üyeleriyle işbirliğini kusursuz hale getirir. İçerik yerel olarak ve/veya uzaktan depolanabilir.

    Astro'da Intlayer'ı Yapılandırmak İçin Adım Adım Kılavuz

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

    1. Bağımlılıkları Yükleyin

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

      bash
      npm install intlayer astro-intlayer# opsiyonel: React islands desteği eklemek isterseniznpm install react react-dom react-intlayer @astrojs/react

      • 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.

    2. Projenizi Yapılandırın

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

      intlayer.config.ts
      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.

    3. Intlayer'ı Astro konfigürasyonunuza entegre edin

      Astro konfigürasyonunuza intlayer eklentisini ekleyin.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});
      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 adlar (aliases) sağlar.

    4. İçeriğinizi Deklare Edin

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

      src/app.content.tsx
      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,md,mdx,yaml,yml}) 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.

    5. Astro'da İçeriği Kullanma

      Sözlükleri doğrudan .astro dosyalarınızda, intlayer'dan dışa aktarılan temel yardımcıları kullanarak tüketebilirsiniz.

      src/pages/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  defaultLocale,  localeMap,  getHTMLTextDir,  type LocalesValues,} from "intlayer";import LocaleSwitcher from "../components/LocaleSwitcher.astro";// Get the current locale from the URL (e.g. /es/about -> 'es')const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;// Get the content for the 'app' dictionaryconst { 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>    <!-- Canonical link: Tells search engines which is the primary version of this page -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Tell Google about all localized versions -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Fallback for users in unmatched languages -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <header>      <LocaleSwitcher />    </header>    <main>      <h1>{title}</h1>    </main>  </body></html>

    6. Yerelleştirilmiş Yönlendirme

      Yerelleştirilmiş sayfaları sunmak için dinamik rota segmentleri oluşturun (örneğin src/pages/[locale]/index.astro):

      src/pages/[locale]/index.astro
      ---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

      Astro entegrasyonu, geliştirme sırasında dile duyarlı yönlendirme ve ortam tanımlamalarına yardımcı olan bir Vite ara yazılımı ekler. Ayrıca diller arasında bağlantı kurmak için kendi mantığınızı veya intlayer araçlarını (örneğin getLocalizedUrl) kullanabilirsiniz.

    7. Dil Seçici Ekleme

      Kullanıcıların diller arasında geçiş yapabilmesi için bir LocaleSwitcher bileşeni oluşturabilirsiniz. Bu bileşen, desteklenen tüm dillerin bir listesini görüntülemeli ve her dilde aynı sayfaya bağlantı vermelidir.

      src/components/LocaleSwitcher.astro
      ---import {  locales,  getLocaleName,  getLocalizedUrl,  getLocaleFromPath,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);---<nav>  {    locales.map((localeItem) => (      <a        href={getLocalizedUrl(pathWithoutLocale, localeItem)}        data-locale={localeItem}        aria-current={localeItem === locale ? "page" : undefined}      >        {getLocaleName(localeItem)}      </a>    ))  }</nav><script>  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const locale = link.getAttribute("data-locale") as LocalesValues;      // Update the locale cookie      setLocaleInStorageClient(locale);    });  });</script><style>  nav {    display: flex;    gap: 1rem;  }  a[aria-current="page"] {    font-weight: bold;    text-decoration: underline;  }</style>

      Kalıcılık Hakkında Not: İstemci tarafı betiğinde setLocaleInStorageClient kullanılması, kullanıcının dil tercihinin bir çerezde saklanmasını sağlar. Bu, Intlayer ara yazılımının seçimi hatırlamasına ve gelecekteki ziyaretlerde kullanıcıyı tercih ettiği dile otomatik olarak yönlendirmesine olanak tanır.

    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.

      src/pages/sitemap.xml.ts
      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.

      src/pages/robots.txt.ts
      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" },  });};

    9. Favori Framework'ünüzü Kullanmaya Devam Edin

      Seçtiğiniz framework'ü kullanarak uygulamanızı oluşturmaya devam edin.

    10. Bağımlılıkları Yükleyin

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

      bash
      npm install intlayer astro-intlayer# opsiyonel: React islands desteği eklemek isterseniznpm install react react-dom react-intlayer @astrojs/react

      • 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.

    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.

    Autocompletion

    Translation Error

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

    tsconfig.json
    {  // ... 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:

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

    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.

    Bilginizi Derinleştirin

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

    Tanstack Start Solid
    Astro ve React