Astro + Lit Sitenizi Intlayer ile Çevirin

İç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 + Lit'de 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 yapay zeka aracısıysanız intlayer-cli init 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 lit lit-intlayer @astrojs/lit
   

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

   • lit Hızlı ve hafif Web Bileşenleri (Web Components) oluşturmak için temel Lit paketi.

   • lit-intlayer Intlayer'ı Lit uygulamalarına entegre etmek için paket. Dil değiştiğinde LitElement'e otomatik olarak yeniden oluşturma (re-render) talimatı veren ReactiveController tabanlı hook'lar (useIntlayer, useLocale, vb.) sağlar.

   • @astrojs/lit Astro sayfaları içinde Lit özel öğelerinin (custom elements) kullanımına olanak tanıyan resmi Astro entegrasyonu.

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ı sunucu tarafı render için içeriği astro-intlayer kütüphanesinin useIntlayer / useLocale kancalarıyla okur ve Lit adası (src/components/lit/LitDemo.ts) sunucu tarafından algılanan yerel ayarı bir prop olarak alıp etkileşimli kısım için lit-intlayer kütüphanesine iletir. İçerik bildirimleri src/ içinde bileşenlerinizin yanında yer alır.

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   .
   ├── src
   │   ├── components
   │   │   └── lit
   │   │       ├── app.content.ts        # App content declaration
   │   │       └── LitDemo.ts            # Lit custom element (content + locale switcher)
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page mounting the custom element
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() and lit() integrations
   ├── 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.

   konfigürasyon dokümantasyonuna
3. 3

   Intlayer'ı Astro konfigürasyonunuza entegre edin

   Astro konfigürasyonunuza intlayer eklentisini ve Lit entegrasyonunu ekleyin.

   astro.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   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.

   lit() entegrasyonu, Astro sayfaları içinde Lit özel öğelerinin kullanımına olanak tanır.

4. 4

   İçeriğinizi Deklare Edin

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

   src/components/lit/app.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t, type Dictionary } from "intlayer";
   
   const litDemoContent = {
     key: "lit-demo",
     content: {
       greeting: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         tr: "Merhaba Dünya",
       }),
       description: t({
         en: "Welcome to my multilingual Astro + Lit site.",
         fr: "Bienvenue sur mon site Astro + Lit multilingue.",
         es: "Bienvenido a mi sitio Astro + Lit multilingüe.",
         tr: "Çok dilli Astro + Lit siteme hoş geldiniz.",
       }),
     },
   } satisfies Dictionary;
   
   export default litDemoContent;
   

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

   içerik deklarasyon dokümantasyonuna
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.

   Lit özel öğeleri, bir istemci <script>'i aracılığıyla içe aktarılır ve gövdeye (body) yerleştirilir.

   src/pages/[...locale]/index.astro

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     getPrefix,
     localeMap,
     defaultLocale,
     getHTMLTextDir,
   } from "intlayer";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   // Ara yazılım tarafından çözümlenen yerel ayar (ör. /tr/about -> 'tr')
   const { locale } = useLocale();
   
   // Bu yerel ayar için 'lit-demo' sözlüğünün içeriği
   const { greeting } = useIntlayer("lit-demo");
   ---
   
   <!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>{greeting}</title>
   
       <!-- Kurallı (Canonical) Bağlantı -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang Bağlantıları -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- Lit özel öğesi - sunucu tarafından algılanan dili bir özellik (property) olarak alır -->
       <lit-demo locale={locale}></lit-demo>
     </body>
   </html>
   
   <script>
     import "../../components/lit/LitDemo";
   </script>
   

   İçeriğinizi alt, title, href, aria-label gibi string bir öznitelikte kullanmak istiyorsanız, işlevin değerini şu şekilde kullanabilirsiniz:

   tsx

   İç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)} />
   

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

   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.

6. 6

   Bir Lit Özel Öğesi (Custom Element) Oluşturun

   Bir Lit özel öğesi oluşturun. İstemci tarafı çeviri singleton'ını başlatmak için sunucu tabanlı locale özelliğini (attribute) kullanarak connectedCallback içinde installIntlayer'ı çağırın.

   src/components/lit/LitDemo.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { LitElement, html } from "lit";
   import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   class LitDemo extends LitElement {
     static properties = {
       locale: { type: String },
     };
   
     locale: LocalesValues = "en" as LocalesValues;
   
     private _content = useIntlayer(this, "lit-demo");
     private _localeCtrl = useLocale(this, {
       onLocaleChange: (newLocale: LocalesValues) => {
         window.location.href = getLocalizedUrl(
           window.location.pathname,
           newLocale
         );
       },
     });
   
     override connectedCallback() {
       super.connectedCallback();
       // Sunucu tarafından algılanan dille başlatın
       installIntlayer({ locale: this.locale as any });
     }
   
     override render() {
       const { greeting, description } = this._content;
       const {
         locale: currentLocale,
         availableLocales,
         setLocale,
       } = this._localeCtrl;
   
       return html`
         <div>
           <h1>${greeting}</h1>
           <p>${description}</p>
           <!-- LitElement içinde oluşturulan dil seçici -->
           <div class="locale-switcher">
             <span class="switcher-label">Dili değiştir:</span>
             <div class="locale-buttons">
               ${availableLocales.map(
                 (localeItem) => html`
                   <button
                     class="locale-btn ${
                       localeItem === currentLocale ? "active" : ""
                     }"
                     ?disabled=${localeItem === currentLocale}
                     @click=${() => setLocale(localeItem)}
                   >
                     <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                     <span class="ls-current-name"
                       >${getLocaleName(localeItem, currentLocale)}</span
                     >
                     <span class="ls-code">${localeItem.toUpperCase()}</span>
                   </button>
                 `
               )}
             </div>
           </div>
         </div>
       `;
     }
   }
   
   customElements.define("lit-demo", LitDemo);
   

   locale özelliği, Astro sayfasından (sunucu algılaması) aktarılır ve connectedCallback içinde installIntlayer'ı başlatmak için kullanılır. Bu, öğe içindeki tüm ReactiveController hook'ları için başlangıç dilini ayarlar.

   useIntlayer, bir ReactiveController olarak kaydedilir. Dil değiştiğinde öğenin otomatik olarak yeniden oluşturulmasını (re-render) talimatını verir, bu nedenle ek abonelik (subscription) mantığı gerekmez.

7. 7

   Bir Dil Seçici Ekleme

   Dil değiştirme işlevselliği doğrudan Lit özel öğesinin render() yöntemine entegre edilmiştir (yukarıdaki Adım 6'ya bakın). lit-intlayer'dan useLocale kullanır ve kullanıcı yeni bir dil seçtiğinde yerelleştirilmiş URL'ye yönlendirir:

   src/components/lit/LitDemo.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   // LitElement sınıfı içinde, Adım 6'daki useLocale kurulumundan sonra:
   
   private _localeCtrl = useLocale(this, {
     onLocaleChange: (newLocale: LocalesValues) => {
       // Dil değişikliğinde yerelleştirilmiş URL'ye yönlendir
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   
   override render() {
     const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;
   
     return html`
       <div class="locale-switcher">
         <span class="switcher-label">Dili değiştir:</span>
         <div class="locale-buttons">
           ${availableLocales.map(
             (localeItem) => html`
               <button
                 class="locale-btn ${localeItem === currentLocale ? "active" : ""}"
                 ?disabled=${localeItem === currentLocale}
                 @click=${() => setLocale(localeItem)}
               >
                 <span class="ls-own-name">${getLocaleName(localeItem)}</span>
                 <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>
                 <span class="ls-code">${localeItem.toUpperCase()}</span>
               </button>
             `
           )}
         </div>
       </div>
     `;
   }
   

   Lit Reaktivitesi Hakkında Not: useLocale bir ReactiveController döndürür. setLocale çağrıldığında, kontrolör otomatik olarak yeniden oluşturma talep eder ve manuel DOM manipülasyonu gerekmeden etkin buton durumunu günceller.

   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.

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ı kontrol 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. 17

   Bileşenlerinizin içeriğini çıkarın

   İsteğe bağlı

   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.

   derleyici

   çıkarıcı

   Kurulum 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 = {
     // ... 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;
   

   Çıkarma komutuBabel derleyicisi

   Bileşenlerinizi dönüştürmek ve içeriği çıkarmak için çıkarıcıyı çalıştırı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. Decorator sözdizimini kullanıyorsanız, derleyici seçeneklerinizde experimentalDecorators'ı etkinleştirdiğinizden emin olun.

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

{
  compilerOptions: {
    // ...
    experimentalDecorators: true,
    useDefineForClassFields: false, // Lit'te decorator desteği için gereklidir
  },
  "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.

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 fazlerini öğrenmek isterseniz, içeriğinizi dış kaynaklara aktarmak için Görsel Editör'ü uygulayabilir veya CMS kullanabilirsiniz.

Sıkça Sorulan Sorular