在 SvelteKit 中使用 Langsys

各处的模式都相同:服务器只获取一次目录(写入密钥保留在服务器端),客户端则使用只读密钥,基于该预置数据初始化 langsys-js-svelte,无需重复获取。翻译本身在浏览器中完成:服务器发送的 HTML 使用基础语言,这也是搜索引擎所索引的内容,页面在加载时会切换为访问者的语言。

1 · 在 +layout.server.ts 中加载目录

服务器端的 load 函数在每次页面渲染时获取一次词库;SvelteKit 会将其序列化到页面数据中。写入密钥保留在服务器端,客户端获得的是只读密钥。两端看到的是同一份词库——客户端只是跳过了首次获取。

// src/routes/+layout.server.ts
import { LANGSYS_API_KEY, LANGSYS_PROJECT_ID } from '$env/static/private';

export const load = async ({ fetch }) => {
  const locale = 'en-US'; // from cookie / Accept-Language
  const res = await fetch(
    `https://api.langsys.dev/api/projects/${LANGSYS_PROJECT_ID}/translations?locale=${locale}`,
    { headers: { 'x-Authorization': LANGSYS_API_KEY } }
  );
  const { data: translations } = await res.json();
  return { locale, translations };
};

2 · 在 +layout.svelte 中初始化

标准的 Svelte writable 就是语言区域存储——Svelte 绑定会将其适配给 SDK 使用。初始化在 onMount 中运行，并使用预置的目录，因此不会重复获取任何内容。onMount 运行后，文本会从基础语言切换为访客的语言。

<!-- src/routes/+layout.svelte -->
<script>
  import { onMount } from 'svelte';
  import { writable } from 'svelte/store';
  import { LangsysApp } from 'langsys-js-svelte';
  import { PUBLIC_LANGSYS_API_KEY, PUBLIC_LANGSYS_PROJECT_ID } from '$env/static/public';

  export let data;

  const locale = writable(data.locale);

  onMount(() => {
    LangsysApp.init({
      projectid: PUBLIC_LANGSYS_PROJECT_ID,
      key: PUBLIC_LANGSYS_API_KEY, // read-only
      UserLocaleStore: locale,
      initialTranslations: data.translations,
      initialTranslationsLocale: data.locale,
      ssrTokenStrategy: 'client',
    });
  });
</script>

<slot />

3 · 在下方任意位置使用

从这里开始就是纯 Svelte SDK 的用法了:在任意组件中使用 $t(signal 原生满足 Svelte 的 store 约定),用 $locale = 'fr-FR' 即可在整个应用范围内切换语言。

<script>
  import { t } from 'langsys-js-svelte';
</script>

<h1>{$t('Welcome to our store', 'Home')}</h1>