Intlayer Kullanarak Elysia Backend Web Sitenizi Çevirme | Uluslararasılaştırma (i18n)

elysia-intlayer Elysia uygulamaları için güçlü bir uluslararasılaştırma (i18n) eklentisidir ve istemcinin tercihlerine dayalı olarak yerelleştirilmiş yanıtlar sağlayarak backend hizmetlerinizi küresel olarak erişilebilir hale getirmeye yönelik tasarlanmıştır.

GitHub'da paket uygulamasını görüntüleyin: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

Pratik Kullanım Senaryoları

• Backend Hatalarını Kullanıcının Dilinde Görüntüleme: Bir hata oluştuğunda, mesajları kullanıcının ana dilinde görüntülemek anlayışı iyileştirir ve hayal kırıklığını azaltır. Bu, toast veya modal gibi ön-uç bileşenlerinde gösterilebilecek dinamik hata mesajları için özellikle faydalıdır.
• Çok Dilli İçerik Alma: Bir veritabanından içerik çeken uygulamalar için uluslararasılaştırma, bu içeriği birden fazla dilde sunabileceğinizi sağlar. Bu, ürün açıklamaları, makaleler ve diğer içeriği kullanıcı tarafından tercih edilen dilde görüntülemesi gereken e-ticaret siteleri veya içerik yönetim sistemleri gibi platformlar için çok önemlidir.
• Çok Dilli E-posta Gönderme: İşlemsel e-postalar, pazarlama kampanyaları veya bildirimler olsun, alıcının dilinde e-posta göndermek katılımı ve etkinliği önemli ölçüde artırabilir.
• Çok Dilli Push Bildirimleri: Mobil uygulamalar için, push bildirimlerini kullanıcının tercih ettiği dilde göndermek etkileşimi ve tutunduğunu artırabilir. Bu kişisel dokunuş, bildirimleri daha ilgili ve işlem yapılabilir hissettirebilir.
• Diğer İletişimler: Backend'den gelen SMS mesajları, sistem uyarıları veya kullanıcı arayüzü güncellemeleri gibi her türlü iletişim, kullanıcının dilinde olmasından fayda sağlar, netliği sağlar ve genel kullanıcı deneyimini iyileştirir.

Backend'i uluslararasılaştırarak, uygulamanız yalnızca kültürel farklılıklara saygı göstermekle kalmaz, aynı zamanda global pazar ihtiyaçlarıyla daha iyi uyumlanır ve bu, hizmetlerinizi dünya çapında ölçeklendirmenin önemli bir adımıdır.

Başlangıç

Bkz. Uygulama Şablonu GitHub'da.

Kurulum

elysia-intlayer kullanmaya başlamak için npm kullanarak paketi kurun:

npx intlayer init --interactive

--interactive bayrağı isteğe bağlıdır. Bir AI ajanı iseniz intlayer-cli init komutunu kullanın.

Bu komut ortamınızı algılayacak ve gerekli paketleri kuracaktır. Örneğin:

npm install intlayer elysia-intlayer

Elysia Bun runtime'ını hedefler. elysia-intlayer, Node tabanlı Intlayer pluginlerinin kullandığı cls-hooked kütüphanesi yerine AsyncLocalStorage'a dayanır; çünkü Bun async_hooks.createHook fonksiyonunu implemente etmez.

Kurulum

Proje kök dizininde intlayer.config.ts dosyası oluşturarak uluslararasılaştırma ayarlarını yapılandırın:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * İstenen locale bulunamazsa fallback olarak kullanılan varsayılan locale.
     */
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

İçeriğinizi Bildirin

Çevirileri depolamak için içerik bildirimlerini oluşturun ve yönetin:

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      tr: "İngilizce'de döndürülen içerik örneği",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

İçerik bildirimleriniz, contentDir dizinine dahil oldukları sürece (varsayılan olarak ./src) uygulamanızın herhangi bir yerinde tanımlanabilir. Ve içerik bildirimi dosya uzantısıyla eşleşmelidir (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Daha fazla ayrıntı için içerik bildirimi belgelerine bakın.

Elysia Uygulaması Kurulumu

Elysia uygulamanızı elysia-intlayer kullanacak şekilde kurun:

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia()
  // Uluslararasılaştırma eklentisini yükle
  .use(intlayer())
  // Rotalar
  .get("/", ({ intlayer }) => ({
    // Bu istek için kullanılan locale, `Accept-Language` üzerinden anlaşıldı veya depolamadan okundu
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      tr: "Merhaba",
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Plugin, context'ini global bir derive üzerinden kaydeder ve Elysia bunu Partial<{ intlayer: IntlayerContext }> olarak tipler. .use(intlayer()) sonrasında kaydedilen route'larda değer çalışma zamanında her zaman mevcuttur; bu yüzden strict modda TypeScript'i memnun etmek için non-null assertion (intlayer!.locale) veya optional chaining kullanın.

Route context şunları sunar:

Aynı helper'lar standalone export olarak da sunulur. Mevcut isteği AsyncLocalStorage üzerinden çözdükleri için context'i destructure etmeden çağırabilirsiniz:

import { Elysia } from "elysia";
import { intlayer, t, getDictionary, getIntlayer } from "elysia-intlayer";
import dictionaryExample from "./index.content";

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      tr: "İngilizce'de döndürülen içerik örneği",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

İstek bağlamı, yanıt map'lendiği anda serbest bırakılır; böylece bağımsız helper'lar hiçbir zaman sonlanmış bir isteğe karşı çözümlenmez. Eklentinin işlediği bir isteğin dışında çağrıldıklarında, yapılandırılmış varsayılan locale'e geri dönerler.

Uygulamanızı Çalıştırın

Intlayer scriptlerini package.json dosyanıza ekleyin. intlayer build, içerik bildirimlerinizi .intlayer dizinine derler ve TypeScript tiplerini üretir:

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Ardından sunucuyu başlatın:

bun run dev

Accept-Language ile locale müzakeresini test edin:

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

bun run src/index.ts öncesinde intlayer build kesinlikle zorunlu değildir: plugin, Elysia uygulaması açılırken de sözlükleri hazırlar. Önceden çalıştırmak, üretilen tipleri editörünüz için güncel tutar ve ilk istekteki build maliyetinden kaçınmanızı sağlar.

Uyumluluk

elysia-intlayer tamamen uyumludur:

• react-intlayer React uygulamaları için
• next-intlayer Next.js uygulamaları için
• vite-intlayer Vite uygulamaları için

Ayrıca, tarayıcılar ve API istekleri dahil olmak üzere çeşitli ortamlarda herhangi bir uluslararasılaştırma çözümüyle sorunsuz bir şekilde çalışır.

Varsayılan olarak plugin, locale'i şu sırayla çözer:

1. INTLAYER_LOCALE çerezi.
2. x-intlayer-locale header'ı.
3. Accept-Language header müzakeresi.

Locale tespiti için kullanılan çerezi ve header’ı özelleştirebilirsiniz:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Diğer yapılandırma seçenekleri
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

Yapılandırma ve ileri konular hakkında daha fazla bilgi için lütfen dokumentasyonumuzu ziyaret edin.

TypeScript'i Yapılandırma

elysia-intlayer, uluslararasılaştırma sürecini geliştirmek için TypeScript'in güçlü yeteneklerinden yararlanır. TypeScript'in statik yazı sistemi, her çeviri anahtarının dikkate alınmasını sağlayarak eksik çevirilerin riskini azaltır ve bakımlanabilirliği artırır.

Otomatik olarak oluşturulan türlerin (varsayılan olarak ./types/intlayer.d.ts konumunda) tsconfig.json dosyanıza dahil edildiğinden emin olun.

{
  // ... Mevcut TypeScript yapılandırmalarınız
  "include": [
    // ... Mevcut TypeScript yapılandırmalarınız
    ".intlayer/**/*.ts", // Otomatik oluşturulan türleri dahil et
  ],
}

VS Code Extension

Intlayer ile geliştirme deneyiminizi iyileştirmek için, resmi Intlayer VS Code Extension'ı yükleyebilirsiniz.

VS Code Marketplace'ten Yükle

Bu extension şunları sağlar:

• Autocompletion çeviri anahtarları için.
• Real-time hata tespiti eksik çeviriler için.
• Inline previews çevrilen içeriğin.
• Quick actions çevirileri kolayca oluşturmak ve güncellemek için.

Extension'ın nasıl kullanılacağı hakkında daha fazla bilgi için, Intlayer VS Code Extension dokumentasyonuna bakınız.

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaları yoksaymak önerilir. Bu, bunları Git deponuza işlemekten kaçınmanızı sağlar.

Bunu yapmak için, .gitignore dosyanıza aşağıdaki yönergeleri ekleyebilirsiniz:

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