在 Nuxt 中使用 Langsys

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

1 · 由服务器路由代理目录

由 Nitro 路由获取目录,因此写入密钥会保留在私有运行时配置中——浏览器只会与您自己的 /api 路由通信。写入密钥始终保留在服务器上,客户端获得的是只读密钥。两端看到的是同一份目录——客户端只是跳过了首次获取。

// server/api/langsys.get.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();
  const locale = (getQuery(event).locale as string) ?? 'en-US';
  const res = await $fetch<{ data: unknown }>(
    `https://api.langsys.dev/api/projects/${config.langsysProjectId}/translations`,
    { query: { locale }, headers: { 'x-Authorization': config.langsysApiKey } }
  );
  return { locale, translations: res.data };
});

2 · 在 SSR 期间预置数据,在客户端初始化

useAsyncData 在服务器上执行数据获取，并将载荷序列化到页面中，这样客户端无需重新获取即可据此初始化。初始化在 onMounted 中运行——该 SDK 是浏览器端 SDK；Nuxt 的服务器部分只负责提供数据。

<!-- app.vue -->
<script setup lang="ts">
import { LangsysApp, createLocaleStore } from 'langsys-js-vue';
import type { iCategories } from 'langsys-js-vue';

const { data } = await useAsyncData('langsys', () =>
  $fetch('/api/langsys', { query: { locale: 'en-US' } })
);

const store = createLocaleStore(data.value!.locale);

onMounted(() => {
  LangsysApp.init({
    projectid: useRuntimeConfig().public.langsysProjectId,
    key: useRuntimeConfig().public.langsysApiKey, // read-only
    UserLocaleStore: store,
    initialTranslations: data.value!.translations as iCategories,
    initialTranslationsLocale: data.value!.locale,
    ssrTokenStrategy: 'client',
  });
});
</script>

<template>
  <NuxtPage />
</template>

3 · 在下方任意位置使用

从这里开始,它就是普通的 Vue SDK:在任意组件中使用 useT(),用 store.set() 切换语言区域。如果你的应用已经在 ref(Pinia、useState)中管理语言区域,请使用 Vue 绑定的 refToLocaleSource 进行适配,而不必迁移到 createLocaleStore。

<script setup>
import { useT } from 'langsys-js-vue';
const t = useT();
</script>

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