Intlayer kullanarak Vite ve Lit web sitenizi çevirin | Uluslararasılaştırma (i18n)

İçindekiler

Neden alternatifler yerine Intlayer?

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

Vite ve Lit Uygulamasında Intlayer Kurulumu İçin Adım Adım Kılavuz

1. 1

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

   Gerekli paketleri npm kullanarak yükleyin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

   • intlayer

     Yapılandırma yönetimi, çeviri, içerik bildirimi, transpilasyon ve CLI komutları için uluslararasılaştırma araçları sağlayan temel paket.

   • lit-intlayer Intlayer'ı Lit uygulamalarıyla entegre eden paket. Dil değiştiğinde LitElement'lerin otomatik olarak yeniden oluşturulması için ReactiveController tabanlı kancalar (useIntlayer, useLocale vb.) sağlar.

   • vite-intlayer Intlayer'ı Vite paketleyici ile entegre etmek için Vite eklentisini ve kullanıcının tercih ettiği dili algılamayı, çerezleri yönetmeyi ve URL yönlendirmesini işlemeyi sağlayan ara yazılımı içerir.

2. 2

   Projenizin Yapılandırılması

   Uygulamanızın dillerini yapılandırmak için bir yapılandırma 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,
         // Diğer dilleriniz
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Bu yapılandırma dosyası aracılığıyla, yerelleştirilmiş URL'ler, ara yazılım yönlendirmesi, çerez adları, içerik bildirimlerinizin konumu ve uzantısı, konsoldaki Intlayer günlüklerini devre dışı bırakma ve daha fazlasını ayarlayabilirsiniz. Kullanılabilir parametrelerin tam listesi için yapılandırma belgelerine bakın.

3. 3

   Intlayer'ı Vite Yapılandırmanıza Entegre Edin

   Yapılandırmanıza intlayer eklentisini ekleyin.

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [intlayer()],
   });

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

4. 4

   Giriş Noktasında Intlayer'ı Başlatın

   Herhangi bir özel öğe kaydedilmeden önce installIntlayer() işlevini çağırın, böylece ilk öğe bağlandığında küresel dil tekili hazır olur.

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayer } from "lit-intlayer";// Herhangi bir LitElement DOM'a bağlanmadan önce çağrılmalıdır.installIntlayer();// Özel öğelerinizi içe aktarın ve kaydedin.import "./my-element.js";

   Ayrıca md() içerik bildirimlerini (Markdown) kullanıyorsanız, markdown oluşturucuyu da yükleyin:

   src/main.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

5. 5

   İçeriğinizi Bildirin

   Çevirileri saklamak için içerik bildirimlerinizi oluşturun ve yönetin:

   src/app.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Lit",
   
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       litLogo: t({
         en: "Lit logo",
         fr: "Logo Lit",
         es: "Logo Lit",
       }),
   
       count: t({
         en: "count is {{count}}",
         fr: "le compte est {{count}}",
         es: "el recuento es {{count}}",
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Lit logos to learn more",
         fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;

   İçerik bildirimleriniz, contentDir dizinine (varsayılan olarak ./src) dahil edildikleri ve içerik bildirimi 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 ayrıntı için içerik bildirimi belgelerine bakın.

6. 6

   LitElement'inizde Intlayer'ı Kullanın

   Bir LitElement içinde useIntlayer kullanın. Aktif dil değiştiğinde otomatik olarak yeniden oluşturma işlemini tetikleyen bir ReactiveController proxy'si döndürür - ekstra kurulum gerekmez.

   src/my-element.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer kendisini bir ReactiveController olarak kaydeder.  // Dil değiştiğinde öğe otomatik olarak yeniden oluşturulur.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

   Yerel bir HTML özniteliğinde (örneğin alt, aria-label, title) çevrilmiş dizeye ihtiyacınız olduğunda, yaprak düğüm üzerinde .value işlevini çağırın:

   typescript

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

7. 7

   İçeriğinizin Dilini Değiştirin

   İsteğe bağlı

   İçeriğinizin dilini değiştirmek için useLocale denetleyicisi tarafından sunulan setLocale yöntemini kullanın.

   src/locale-switcher.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

8. 8

   Markdown ve HTML İçeriğini Oluşturun

   İsteğe bağlı

   Intlayer md() ve html() içerik bildirimlerini destekler. Lit'te, derlenmiş çıktı unsafeHTML yönergesi aracılığıyla ham HTML olarak enjekte edilir.

   Derlenmiş HTML'yi öğenizde oluşturun:

   src/my-element.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}

   TIP

   String(content.editNote), IntlayerNode üzerinde ham Markdown dizesini döndüren toString() işlevini çağırır. Bir HTML dizesi almak için bunu compileMarkdown işlevine geçirin, ardından Lit'in unsafeHTML yönergesiyle oluşturun.

9. 9

   Uygulamanıza Yerelleştirilmiş Yönlendirme Ekleyin

   İsteğe bağlı

   Her dil için benzersiz rotalar oluşturmak (SEO için yararlıdır), Intlayer'ın localeMap / localeFlatMap yardımcılarını ve sunucu tarafı dil algılama için intlayerProxy Vite eklentisini içeren bir istemci tarafı yönlendirici kullanabilirsiniz.

   İlk olarak, Vite yapılandırmanıza intlayerProxy ekleyin:

   Üretimde intlayerProxy kullanmak için vite-intlayer paketini devDependencies'tan dependencies'a taşımanız gerektiğini unutmayın.

   vite.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { defineConfig } from "vite";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [intlayer(), intlayerProxy()],
   });

10. 10

    Dil Değiştiğinde URL'yi Değiştirin

    İsteğe bağlı

    Dil değiştiğinde tarayıcı URL'sini güncellemek için dil değiştiriciyle birlikte useRewriteURL kullanın:

    src/locale-switcher.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Dil değiştiğinde geçerli URL'yi otomatik olarak yeniden yazar.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

11. 11

    HTML Dil ve Yön Özniteliklerini Değiştirin

    İsteğe bağlı

    Erişilebilirlik ve SEO için <html> etiketinin lang ve dir özniteliklerini geçerli dille eklenecek şekilde güncelleyin.

    src/my-element.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- içeriğiniz -->`;  }}

12. 12

    Bileşenlerinizin İç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ı önerir.

    Kurulumu yapmak 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ı 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;

(İsteğe bağlı) Sitemap ve robots.txt (build zamanı üretimi)

Intlayer, generateSitemap ve getMultilingualUrls ile tarayıcılar için çok dilli sitemap.xml ve robots.txt üretip bunları public/ klasörüne otomatik yazmanıza yardımcı olur. Genelde Vite’tan önce küçük bir Node betiği çalıştırılır (ör. npm predev / prebuild kancaları).

Sitemap

Intlayer sitemap oluşturucusu yerel ayarlarınıza uyar ve tarayıcılar için metadata ekler.

Üretilen sitemap xhtml:link (hreflang) ad alanını destekler. Düz URL listesi yerine, her sayfanın tüm dil sürümleri çift yönlü bağlanır (ör. /about, /fr/about veya /about?lang=fr - yönlendirme moduna bağlı).

Robots.txt

getMultilingualUrls kullanarak Disallow kurallarının hassas yolların tüm yerelleştirilmiş varyantlarını kapsamasını sağlayın.

1. Proje köküne generate-seo.mjs ekleyin

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Betik intlayer içe aktarabilmeli; paket kurulu olmalı. Üretimde ortam değişkeni SITE_URL ayarlayın (ör. CI).

Node ESM için generate-seo.mjs tercih edin. generate-seo.js kullanıyorsanız package.json içinde "type": "module" veya ESM’yi başka şekilde etkinleştirin.

2. Betiği Vite’tan önce çalıştırın

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

pnpm veya yarn kullanıyorsanız komutları uyarlayın. CI’dan da çağrılabilir.

TypeScript Yapılandırması

TypeScript yapılandırmanızın otomatik oluşturulan tipleri içerdiğinden emin olun.

{  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}

experimentalDecorators ve useDefineForClassFields: false, dekoratör desteği için Lit tarafından gereklidir.

Git Yapılandırması

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

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

# 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 yükleyin

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 önizlemeleri.
• Çevirileri kolayca oluşturmak ve güncellemek için hızlı işlemler.

Uzantının nasıl kullanılacağı hakkında daha fazla ayrıntı için Intlayer VS Code Uzantısı belgelerine bakın.

Daha Fazlasına Gidin

Daha ileri gitmek için görsel düzenleyiciyi uygulayabilir veya CMS kullanarak içeriğinizi dışsallaştırabilirsiniz.