Intlayer kullanarak Vite ve Lit web sitenizi ç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:

• Bileşen düzeyinde bildirimsel sözlükler kullanarak çevirileri kolayca yönetin.
• Metadataları, rotaları ve içeriği dinamik olarak yerelleştirin.
• Otomatik oluşturulan tiplerle TypeScript desteğini sağlayın, otomatik tamamlama ve hata algılamayı iyileştirin.
• Dinamik dil algılama ve değiştirme gibi gelişmiş özelliklerden yararlanın.

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

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

Gerekli paketleri npm kullanarak yükleyin:

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.

Adım 2: Projenizin Yapılandırılması

Uygulamanızın dillerini yapılandırmak için bir yapılandırma dosyası oluşturun:

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.

Adım 3: Intlayer'ı Vite Yapılandırmanıza Entegre Edin

Yapılandırmanıza intlayer eklentisini ekleyin.

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.

Adım 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.

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:

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

Adım 5: İçeriğinizi Bildirin

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

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

Adım 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.

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)} />`;

(İsteğe Bağlı) Adım 7: İçeriğinizin Dilini Değiştirin

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

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>    `;  }}

(İsteğe Bağlı) Adım 8: Markdown ve HTML İçeriğini Oluşturun

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:

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.

(İsteğe Bağlı) Adım 9: Uygulamanıza Yerelleştirilmiş Yönlendirme Ekleyin

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.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), intlayerProxy()],
});

(İsteğe Bağlı) Adım 10: Dil Değiştiğinde URL'yi Değiştirin

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

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>    `;  }}

(İsteğe Bağlı) Adım 11: HTML Dil ve Yön Özniteliklerini Değiştirin

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

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 -->`;  }}

(İsteğe Bağlı) Adım 12: Bileşenlerinizin İç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ı önerir.

Kurulumu yapmak 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ı 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 (derleme 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.