← Cloudflare Pages / pages / tutorials

Lokalizace webu pomocí HTMLRewriter

V tomto tutoriálu vytvoříte ukázkový engine pro internacionalizaci a lokalizaci (běžně označovaný jako i18n a l10n) pro vaši aplikaci, zobrazovat obsah vašeho webu a automaticky jej překládat podle polohy vašich návštěvníků ve světě.

Tento tutoriál používá HTMLRewriter třída zabudovaná do runtime Cloudflare Workers, která umožňuje parsovat a přepisovat HTML přímo v globální síti Cloudflare. Díky tomu mohou vývojáři efektivně a transparentně přizpůsobovat své aplikace Workers.

Příklad webu, který byl úspěšně lokalizován do japonštiny, němčiny a angličtiny

Než budete pokračovat

Všechny průvodce frameworky předpokládají, že již máte základní znalosti Git ↗. Pokud s Gitem začínáte, podívejte se na tento shrnutá příručka ke Gitu ↗ jak nastavit Git na svém lokálním počítači.

Pokud klonujete přes SSH, musíte vygenerujte SSH klíče ↗ na každém počítači, který používáte pro push nebo pull z GitHubu.

Viz dokumentace GitHub ↗ a Dokumentace Git ↗ s dalšími informacemi.

Předpoklady

Tento tutoriál pracuje s existujícím webem. Pro zjednodušení použijete bezplatnou šablonu HTML5 z HTML5 UP ↗. S tímto webem jako základem použijete HTMLRewriter funkcionalitu platformy Workers a přidat vrstvu i18n, která web automaticky přeloží podle jazyka uživatele.

Pokud chcete nasadit vlastní verzi webu, zdrojový kód najdete na GitHubu ↗. Pokyny k nasazení této aplikace najdete v souboru README daného projektu.

Vytvořte novou aplikaci

Vytvořte novou aplikaci pomocí create-cloudflare, CLI nástroj pro vytváření a nasazování nových aplikací do Cloudflare.

npm create cloudflare@latest -- i18n-example

Při nastavení vyberte následující možnosti:

Pro S čím byste chtěli začít?, vyberte Framework Starter.
Pro Jaký vývojový framework chcete použít?, vyberte React.
Pro, Chcete nasadit svou aplikaci?, vyberte No.

Nově vygenerovaný i18n-example projekt bude obsahovat dvě složky: public a src tyto obsahují soubory pro aplikaci React:

cd i18n-example
ls

public src package.json

Ve vygenerovaném projektu musíme provést několik úprav. Nejprve chceme nahradit obsah uvnitř souboru public adresář s výchozím vygenerovaným HTML kódem pro šablonu HTML5 UP, který vidíte na snímku obrazovky s ukázkou: stáhněte vydání ↗ (soubor ZIP) s kódem tohoto projektu a zkopírujte public složku do vlastního projektu a začněte.

Dále vytvoříme adresář functions s index.js soubor, sem budete zapisovat logiku aplikace.

mkdir functions
cd functions
touch index.js

Kromě toho odebereme src/ adresář, protože jeho obsah není pro tento projekt potřeba. Po aktualizaci statického HTML pro tento projekt se můžete zaměřit na skript uvnitř functions složka, na index.js.

Vysvětlení `data-i18n-key`

HTMLRewriter třída dostupná v runtime Workers umožňuje vývojářům parsovat HTML a psát JavaScript pro dotazování a úpravu každého prvku stránky.

Ukázkový web v tomto tutoriálu je základní jednostránkový projekt HTML, který se nachází ve public adresář. Obsahuje h1 element s textem Example Site a řadu p elementy s odlišným textem:

Ukázkový kód zobrazený v Chrome DevTools s prvky popsanými výše

Na této stránce je jedinečné přidání datové atributy ↗ v HTML: vlastní atributy definované na řadě elementů této stránky. data-i18n-key na h1 značku na této stránce, stejně jako mnoho dalších p značek značí, že pro tento text existuje odpovídající klíč internacionalizace, který by se měl použít k vyhledání překladu:

<!-- source clipped from i18n-example site -->

<div class="inner">
	<h1 data-i18n-key="headline">Example Site</h1>
	<p data-i18n-key="subtitle">This is my example site. Depending o...</p>
	<p data-i18n-key="disclaimer">Disclaimer: the initial translations...</p>
</div>

Použití HTMLRewriter, zpracujete HTML uvnitř ./public/index.html stránka. Když data-i18n-key atribut nalezen, měli byste pomocí jeho hodnoty načíst odpovídající překlad z strings objekt. S HTMLRewriter, můžete dotazovat elementy a provádět úkoly, jako je vyhledání datového atributu. Jak však název napovídá, můžete elementy také přepisovat tak, že přeložený řetězec vložíte přímo do HTML.

Další funkce tohoto projektu vychází z Accept-Language hlavičky, která je součástí příchozích požadavků. Jazyk překladu můžete nastavit pro každý požadavek zvlášť, takže uživatelé z celého světa uvidí lokálně relevantní přeloženou stránku.

Používání HTML Rewriter API

Začněte u functions/index.js soubor. Vaše aplikace bude v tomto tutoriálu celá umístěna v tomto souboru.

Do tohoto souboru nejprve přidejte výchozí kód pro spuštění Pages Function.

export function onRequest(context) {
	return new Response("Hello, world!");
}

Důležitá část kódu se nachází ve onRequest funkce. Chcete-li na webu implementovat překlady, vezměte odpověď HTML získanou z env.ASSETS.fetch(request) to vám umožňuje načíst statické aktivum z vašeho projektu Pages a předat ho do nové instance HTMLRewriter. Při vytváření instance HTMLRewriter, můžete připojit handlery pomocí on funkci. Pro tento návod použijete [data-i18n-key] selektor (další informace najdete v dokumentace HTMLRewriter pro pokročilejší použití) k vyhledání všech prvků s data-i18n-key atribut, což znamená, že musí být přeloženy. Každý odpovídající prvek se předá instanci vaší ElementHandler třídu, která bude obsahovat logiku překladu. S vytvořenou instancí HTMLRewriter, transform funkce přijímá response a lze jej vrátit klientovi:

export async function onRequest(context) {
	const { request, env } = context;
	const response = await env.ASSETS.fetch(request);
	return new HTMLRewriter()
		.on("[data-i18n-key]", new ElementHandler(countryStrings))
		.transform(response);
}

Transformace HTML

Váš ElementHandler obdrží každý prvek zpracovaný HTMLRewriter instanci, a díky expresivnímu API můžete u každého příchozího elementu dotazovat informace.

V Jak to funguje, dokumentace popisuje data-i18n-key, vlastní datový atribut, který lze použít k nalezení odpovídajícího přeloženého řetězce pro uživatelské rozhraní webu. V ElementHandler, můžete definovat element funkci, která se zavolá při zpracování každého prvku. Uvnitř element funkci můžete dotazovat vlastní datový atribut pomocí getAttribute:

class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
	}
}

S i18nKey definováno, můžete jej použít k vyhledání odpovídajícího přeloženého řetězce. Nyní nastavíte strings objekt s páry klíč-hodnota odpovídajícími data-i18n-key hodnotu. Prozatím definujete jeden ukázkový řetězec, headline, s německým string, "Beispielseite" ("Example Site") a načíst ji v element funkce:

const strings = {
	headline: "Beispielseite",
};

class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		const string = strings[i18nKey];
	}
}

Vezměte svůj přeložený string a vložte jej do původního elementu pomocí setInnerContent funkce:

const strings = {
	headline: "Beispielseite",
};

class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		const string = strings[i18nKey];
		if (string) {
			element.setInnerContent(string);
		}
	}
}

Chcete-li zkontrolovat, že vše vypadá podle očekávání, použijte náhledovou funkci vestavěnou ve Wrangleru. Zavolejte wrangler pages dev ./public a otevřete živý náhled svého projektu. Příkaz se po každé změně kódu automaticky obnoví.

Tuto překladovou funkci můžete rozšířit tak, aby na základě příchozího požadavku poskytovala překlady pro konkrétní zemi, konkrétně podle jeho Accept-Language hlavičky. Převzetím této hlavičky, její analýzou a předáním rozpoznaného jazyka do své ElementHandler, můžete načíst přeložený řetězec v rodném jazyce uživatele, pokud je definován v strings.

Postup implementace:

Aktualizujte strings objekt, čímž se přidá druhá vrstva párů klíč-hodnota a umožní se vyhledávání řetězců ve formátu strings[country][key].
Předejte countryStrings objekt do našeho ElementHandler, aby ji bylo možné použít během procesu parsování.
Získejte Accept-Language hlavičku z příchozího požadavku, analyzovat ji a předat rozpoznaný jazyk do ElementHandler.

Chcete-li zpracovat Accept-Language hlavičky nainstalujte accept-language-parser ↗ balíček npm:

npm i accept-language-parser

Po importu do svého kódu použijte balíček ke zjištění nejvhodnějšího jazyka klienta na základě Accept-Language hlavičku a předejte ji do ElementHandler. Výsledný kód projektu, včetně ukázkového překladu pro Německo a Japonsko (pomocí Google Translate), vypadá takto:

import parser from "accept-language-parser";

// do not set to true in production!
const DEBUG = false;

const strings = {
	de: {
		title: "Beispielseite",
		headline: "Beispielseite",
		subtitle:
			"Dies ist meine Beispielseite. Abhängig davon, wo auf der Welt Sie diese Site besuchen, wird dieser Text in die entsprechende Sprache übersetzt.",
		disclaimer:
			"Haftungsausschluss: Die anfänglichen Übersetzungen stammen von Google Translate, daher sind sie möglicherweise nicht perfekt!",
		tutorial:
			"Das Tutorial für dieses Projekt finden Sie in der Cloudflare Workers-Dokumentation.",
		copyright: "Design von HTML5 UP.",
	},
	ja: {
		title: "サンプルサイト",
		headline: "サンプルサイト",
		subtitle:
			"これは私の例のサイトです。 このサイトにアクセスする世界の場所に応じて、このテキストは対応する言語に翻訳されます。",
		disclaimer:
			"免責事項：最初の翻訳はGoogle翻訳からのものですので、完璧ではないかもしれません！",
		tutorial:
			"Cloudflare Workersのドキュメントでこのプロジェクトのチュートリアルを見つけてください。",
		copyright: "HTML5 UPによる設計。",
	},
};

class ElementHandler {
	constructor(countryStrings) {
		this.countryStrings = countryStrings;
	}

	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		if (i18nKey) {
			const translation = this.countryStrings[i18nKey];
			if (translation) {
				element.setInnerContent(translation);
			}
		}
	}
}

export async function onRequest(context) {
	const { request, env } = context;
	try {
		let options = {};
		if (DEBUG) {
			options = {
				cacheControl: {
					bypassCache: true,
				},
			};
		}
		const languageHeader = request.headers.get("Accept-Language");
		const language = parser.pick(["de", "ja"], languageHeader);
		const countryStrings = strings[language] || {};

		const response = await env.ASSETS.fetch(request);
		return new HTMLRewriter()
			.on("[data-i18n-key]", new ElementHandler(countryStrings))
			.transform(response);
	} catch (e) {
		if (DEBUG) {
			return new Response(e.message || e.toString(), {
				status: 404,
			});
		} else {
			return env.ASSETS.fetch(request);
		}
	}
}

Nasadit

Váš nástroj i18n vytvořený na Cloudflare Pages je hotový a je čas jej nasadit na vaši doménu.

Chcete-li nasadit svou aplikaci do *.pages.dev subdoménu musíte zadat adresář se statickými aktivy, které se mají zobrazovat, a nakonfigurovat pages_build_output_dir v souboru Wrangler vašeho projektu a nastavte hodnotu na ./public:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "i18n-example",
	"pages_build_output_dir": "./public",
	// Set this to today's date
	"compatibility_date": "2026-08-28"
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "i18n-example"
pages_build_output_dir = "./public"
# Set this to today's date
compatibility_date = "2026-08-28"

Dále musíte nakonfigurovat deploy skript v package.json soubor ve vašem projektu. Přidejte skript deploy s hodnotou wrangler pages deploy:

"scripts": {
  "dev": "wrangler pages dev",
  "deploy": "wrangler pages deploy"
}

Použití wrangler, nasaďte na síť Cloudflare pomocí deploy příkaz:

npm run deploy

V tomto tutoriálu jste vytvořili a nasadili nástroj i18n pomocí HTMLRewriter. Úplný zdrojový kód této aplikace najdete v repozitáři na GitHubu ↗.

Pokud chcete začít vytvářet vlastní projekty, projděte si existující seznam Šablony pro rychlý start.