Paraglide JS - Moderní přístup k internacionalizaci bez runtime overhead

"The best code is the code that doesn't run at runtime." — Každý vývojář, který viděl svůj bundle analyzer

🚀 Co dělá Paraglide JS výjimečným

Paraglide JS je compiler-based internacionalizační knihovna. Místo parsování překladů za běhu aplikace (runtime), jako to dělá většina i18n nástrojů, kompiluje vaše zprávy do tree-shakeable funkcí — což znamená žádný extra runtime, menší bundle a plnou typovou bezpečnost.

Je navržen pro moderní setup — ať už používáte React, SvelteKit, Astro, nebo dokonce vanilla TypeScript. Pod kapotou využívá inlang ekosystém, který přináší strukturované formáty zpráv, editor tooling, linting a automatizaci.

Zkrátka: Paraglide JS změní vaše překladové soubory na něco, čemu váš kompilátor skutečně rozumí — ne jen blob JSON dat.

🧩 Klíčové vlastnosti

• ✅ Tiny bundle size — překlady jsou kompilovány pryč při build time
• ✅ Plná typová bezpečnost — nikdy už si nepřeklepnete klíč překladu
• ✅ Framework-agnostic — funguje s jakýmkoli JavaScript nebo TypeScript projektem
• ✅ Zero async waterfalls — žádné čekání na načítání překladů za běhu
• ✅ Seamless integrace — hladce zapadá do Vite, Rsbuild, Next.js nebo custom setupů

🔍 Jak Paraglide JS funguje pod kapotou

Tradiční i18n knihovny jako react-intl nebo i18next fungují zhruba takto:

1. Načtou JSON soubor s překlady při startu aplikace (nebo lazy load per route)
2. Parsují tento JSON za runtime
3. Hledají klíče v objektu a nahrazují placeholder hodnoty

Problém? Celý tento proces běží při každém renderu v prohlížeči uživatele. Přidáváte JavaScript, který musí být stažen, parsován a spuštěn — i když váš uživatel používá jen jeden jazyk.

Paraglide JS dělá věci jinak:

1. Během build procesu vezme vaše translation soubory (.json, .yaml, nebo inlang formát)
2. Vygeneruje TypeScript funkce pro každý překladový klíč
3. Tyto funkce jsou importovány přímo do vašich komponent
4. Bundler (Vite/Rollup/Webpack) aplikuje tree-shaking — do výsledného bundle se dostane jen to, co skutečně používáte

// Místo toho:
const t = useTranslation();
t("welcome.message") // ❌ Runtime lookup, žádná typová bezpečnost

// Paraglide generuje:
import * as m from "./paraglide/messages"
m.welcome_message() // ✅ Compile-time funkce, plná typová bezpečnost

💡 Kdy použít Paraglide JS

Paraglide JS vyniká, když:

• Stavíte React + TypeScript aplikaci (nebo jakýkoliv silně typovaný frontend)
• Záleží vám na bundle performance a chcete se vyhnout zbytečné runtime logice
• Potřebujete podporovat více frameworků nebo platforem s unified i18n řešením
• Chcete, aby vaše překlady žily v řádném developer workflow — s lintingem, editory a consistency checks
• Plánujete mezinárodní expanzi a chcete, aby správa překladů byla škálovatelná

Pokud startujete greenfield projekt a chcete internacionalizaci zapéct od prvního dne — tohle je pravděpodobně jeden z nejčistších způsobů, jak to udělat.

🛠 Integrace s vaším projektem

Paraglide JS poskytuje oficiální adaptery pro:

• React (včetně Next.js)
• SvelteKit
• Astro
• Solid.js
• Vanilla TypeScript/JavaScript

Pro projekty postavené na Vite (jako TanStack Start, nebo tento blog), integrace vypadá následovně:

// vite.config.ts
import { defineConfig } from 'vite'
import { paraglide } from '@inlang/paraglide-js-adapter-vite'

export default defineConfig({
  plugins: [
    paraglide({
      project: './project.inlang',
      outdir: './src/paraglide',
    }),
  ],
})

Paraglide pak generuje TypeScript funkce do ./src/paraglide/messages.ts, které můžete importovat kamkoli:

import * as m from './paraglide/messages'

export function WelcomeMessage({ userName }: { userName: string }) {
  return <h1>{m.welcome_message({ userName })}</h1>
}

Výhody:

• Autocomplete ve vašem editoru
• Type error, pokud zapomenete parametr (např. userName)
• Žádný runtime overhead — funkce jsou inline během minifikace

⚠️ Co je třeba mít na paměti

• Potřebujete build integraci — Paraglide vyžaduje Vite plugin, Rsbuild config, nebo webpack setup
• Mladší ekosystém — dokumentace a příklady nejsou tak rozsáhlé jako u starších knihoven typu react-intl nebo i18next
• Overkill pro malé projekty — pokud vaše aplikace potřebuje jen pár statických překladů, jednodušší runtime knihovna může stačit
• Edge cases — pluralizace a komplexní ICU Message Format syntaxe může vyžadovat víc konfigurace než u runtime řešení

🎯 Reálný use case: Blog s multi-language support

Představte si, že stavíte blog (jako tento!) a chcete přidat podporu pro češtinu a angličtinu:

Tradiční přístup (runtime i18n):

• Bundle obsahuje všechny překlady pro oba jazyky (nebo lazy load per route)
• JavaScript engine musí parsovat JSON a provádět lookup při každém renderu
• Žádná typová kontrola — překlepy v klíčích najdete až za runtime

S Paraglide JS:

• Build proces vygeneruje dvě verze aplikace (CS a EN), každá s jen potřebnými překlady
• Překlady jsou inline v kódu jako string literály — žádný lookup
• TypeScript error, pokud klíč neexistuje nebo chybí parametr

Výsledek?

• ~15-30 kB menší bundle (záleží na počtu překladů)
• Rychlejší hydratace na klientu (méně JS k parsování)
• Lepší Developer Experience díky autocomplete a type safety

📦 Srovnání s alternativami

💬 Závěr: Je Paraglide JS připraven pro produkci?

Ano — ale záleží na vašem use case.

Pokud:

• Stavíte nový projekt s důrazem na performance
• Používáte TypeScript a chcete typovou bezpečnost všude
• Bundle size je pro vás priorita
• Jste ochotní investovat čas do build setup

...pak je Paraglide JS excelentní volba.

Pokud ale:

• Potřebujete rychle přidat i18n do legacy projektu
• Váš tým není zvyklý na build tooling
• Potřebujete runtime switching jazyků bez reload (edge case)

...možná se budete cítit pohodlněji s react-intl nebo i18next.

🧪 Vyzkoušeli jste Paraglide JS?

Jaká byla vaše zkušenost — smooth, matoucí, nebo překvapivě dobrá? Rád bych slyšel váš názor — podělte se o reálnou zpětnou vazbu a pomozte ostatním rozhodnout, zda je Paraglide JS ready for prime time.