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

İç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:

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

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

1. 1

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

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

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npx intlayer init --interactive
   

   --interactive bayrağı isteğe bağlıdır. Bir AI aracısıysanız intlayer-cli init komutunu kullanın.

   Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer astro-intlayer
   

   • 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 paketleyicisi ile entegre etmek için Astro entegrasyon eklentisini, her isteğin yerel ayarını Astro.locals.intlayer içine çözümleyen bir ara yazılımı ve useIntlayer / useDictionary / useLocale hook'larını içerir. Aynı içe aktarma yolu, .astro frontmatter'ında sunucu uygulamasına ve <script> bloklarında istemci uygulamasına (vanilla-intlayer destekli) çözümlenir.

2. 2

   Projenizi Yapılandırın

   Mimari

   Bu mimaride, astro.config.ts içinde tanımlanan intlayer() entegrasyonu sözlüklerinizi derler ve her isteğin yerel ayarını (locale) çözümleyip Astro.locals.intlayer üzerinde sunan bir ara yazılım (middleware) ekler. Sayfalar src/pages/[...locale]/ rest segmenti altında yer alır, bu sayede varsayılan yerel ayar ön ek olmadan sunulurken diğer tüm yerel ayarlar kendilerine ait özel bir URL alır. .astro dosyaları içeriği astro-intlayer kütüphanesinin useIntlayer / useLocale kancalarıyla okur ve içerik bildirimleri src/ içinde bileşenlerinizin yanında yer alır.

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Yapılandırma

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

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   Intlayer'ı Astro konfigürasyonunuza entegre edin

   Astro konfigürasyonunuza intlayer eklentisini ekleyin.

   astro.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export 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. 4

   İçeriğinizi Deklare Edin

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

   src/app.content.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   Astro'da İçeriği Kullanma

   astro-intlayer tarafından dışa aktarılan hook'ları kullanarak sözlüklerinizi .astro dosyalarında kullanın. Bunlar react-intlayer ile aynı imzaları paylaşır: useIntlayer("key") bir sözlüğün içeriğini ve useLocale() herhangi bir argüman geçirmeden geçerli yerel ayarı döndürür.

   Yerel ayar, entegrasyonun kendi src/middleware.ts dosyanızın önünde sizin için kaydettiği astro-intlayer ara yazılımından gelir. Her istek için yerel ayarı sırasıyla URL ön ekinden, ardından istemci tarafından saklanan yerel ayardan (çerez veya başlık), ardından Accept-Language başlığından çözümler ve Astro.locals.intlayer içinde saklar. Önceden oluşturulmuş sayfalar her ziyaretçi için bir kez oluşturulduğundan yalnızca URL'yi kullanır.

   Ayrıca her sayfaya hreflang ve kurallı (canonical) bağlantılar gibi SEO meta verilerini eklemeli ve kullanıcıların dil değiştirmesine izin vermek için bir dil değiştirici eklemelisiniz.

   src/pages/index.astro

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // Ara yazılım tarafından çözümlenen yerel ayar (ör. /tr/about -> 'tr')
   const { locale } = useLocale();
   
   // Bu yerel ayar için 'app' sözlüğünün içeriği
   const { title } = useIntlayer("app");
   ---
   
   <!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>
   

   Astro.locals.intlayer ayrıca locale, defaultLocale ve availableLocales değerlerini kendi ara yazılımlarınıza ve uç noktalarınıza sunar. İstek yerel ayarını tek bir çağrı için geçersiz kılmak üzere ikinci argüman olarak bir yerel ayar veya seçici iletin (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })).

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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // Tarayıcıda aynı içe aktarma istemci uygulamasına çözümlenir
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Seçimi yerel ayar çerezinde saklar, ardından yerelleştirilmiş URL'ye gider
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   Kalıcılık Hakkında Not: İstemci tarafındaki useLocale içinden setLocale, kullanıcının dil tercihini bir tanımlama bilgisine (cookie) kaydeder. Bu, Intlayer'ın seçimi hatırlamasına ve gelecekteki ziyaretlerde kullanıcıyı otomatik olarak tercih ettiği dile yönlendirmesine olanak tanır: isteğe bağlı olarak oluşturulan sayfalar (output: 'server' veya prerender = false içeren bir bağdaştırıcı), herhangi bir HTML gönderilmeden önce Intlayer ara yazılımı (middleware) tarafından yönlendirilir; statik dosyalar olarak sunulan önceden oluşturulmuş sayfalar ise entegrasyonun her sayfaya eklediği küçük bir komut dosyası tarafından yönlendirilir. Her ikisini de kapatmak için routing.enableProxy değerini false olarak ayarlayın. astro dev modunda, routing.enableProxy değeri true olarak ayarlanmadığı sürece tanımlama bilgisi bir yönlendirme kaynağı olarak yoksayılır, böylece eski bir tanımlama bilgisi üzerinde çalıştığınız sayfaları ele geçiremez.

   Sunucu / İstemci Birlikte Çalışabilirliği: astro-intlayer, frontmatter'da sunucu hook'larına (Astro.locals okuyarak) ve <script> blokları ile adalarda (islands) vanilla-intlayer'ın istemci hook'larına aynı adlar ve içerik yapısıyla çözümlenir. setLocale ve onChange yalnızca istemcide etki eder; istemci deposunu başlatmak için orada bir kez installIntlayer() çağırın. astro-intlayer/client, istemci girişini açıkça sunar.

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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   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 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     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

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   Favori Framework'ünüzü Kullanmaya Devam Edin

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

   • Intlayer + React: React ile Intlayer
   • Intlayer + Vue: Vue ile Intlayer
   • Intlayer + Svelte: Svelte ile Intlayer
   • Intlayer + Solid: Solid ile Intlayer
   • Intlayer + Preact: Preact ile Intlayer
   • Intlayer + Lit: Lit ile Intlayer
10. 15

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

    Mevcut bir codebase'iniz 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 compiler / extractor sunmaktadır.

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

    intlayer.config.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Kalan yapılandırmanız
      compiler: {
        /**
         * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini gösterir.
         */
        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 gösterir.
         *
         * - `true` ise, derleyici bileşen dosyasını diske yeniden yazacaktır. Bu nedenle dönüştürme kalıcı olacak ve derleyici bir sonraki işlem için dönüştürmeyi atlayacaktır. Bu şekilde, derleyici uygulamayı dönüştürebilir ve ardından kaldırılabilir.
         *
         * - `false` ise, derleyici `useIntlayer()` işlev çağrısını yalnızca build çıktısında koda enjekte edecek ve temel codebase'i bozulmamış tutacaktır. Dönüştürme yalnızca bellekte yapılacaktır.
         */
        saveComponents: false,
    
        /**
         * Sözlük anahtarı öneki
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Extract commandBabel compiler

    Çıkartıcıyı çalıştırarak bileşenlerinizi dönüştürün ve içeriği çıkarın

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npx intlayer extract
    

    Bileşenlerinizi dönüştürmek ve içeriği ayıklamak için uygulamanızı derleyin

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npm run build # Veya npm run dev
    

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

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.

Sıkça Sorulan Sorular