通过 Upwork 认识我? 如果您是通过 Upwork 找到我并希望合作,请通过 Upwork 联系我。Upwork 客户在 Upwork 之外发送的消息将不会得到回复。
本地化笔记🌏 本地化

SvelteKit越南语本地化:Paraglide JS与ICU消息配置

使用Paraglide JS本地化SvelteKit为越南语:一键脚手架、vi语言配置、hooks中间件及越南语ICU单一复数类别配置指南。

Dao Huy (Lucas)7分钟8 节
SvelteKit越南语本地化:Paraglide JS与ICU消息配置

💡 要将SvelteKit应用本地化为越南语并使用Paraglide JS:运行npx sv add paraglide,在project.inlang/settings.json中添加vi语言标签,在hooks.server.ts中配置中间件,然后导入类型化消息函数。越南语只有一个ICU复数类别(other),复数消息仅需单一分支。越南语字符串通常比源语言长10-20%。

要点

  • 运行npx sv add paraglide一键搭建完整的Paraglide JS + SvelteKit项目结构。CLI自动创建project.inlang/settings.json、messages/目录,并自动配置Vite插件。
  • 在project.inlang/settings.json的languageTags数组中添加vi。创建messages/vi.json,使用与基础语言文件相同的消息ID填入越南语翻译。
  • 越南语只有一个CLDR复数类别:other。所有ICU复数消息简化为单一分支,不需要单独的one形式。
  • 在hooks.server.ts中使用paraglideMiddleware,在hooks.ts中使用deLocalizeUrl重路由钩子,实现URL语言前缀和正确的SSR语言注入。
  • 越南语字符串通常比英语长10-20%。在375px和390px视口下测试所有按钮标签和导航项目。Web字体子集必须包含越南语完整Unicode块(U+1EA0-U+1EF9)。

SvelteKit越南语本地化需要哪些工作?

将SvelteKit应用本地化为越南语涉及四个独立问题:消息管理、语言路由、数字和日期格式化,以及布局测试。这些问题相互独立,可以逐一解决而不会相互阻塞。

Paraglide JS负责消息管理和语言路由。JavaScript的Intl API使用vi-VN语言区域处理格式化。布局测试是手动步骤,用于发现越南语特有的字体和字符串长度问题。

SvelteKit的服务端渲染增加了一个要求:语言环境必须在服务器端按请求检测,并传递到客户端。Paraglide的中间件通过hooks.server.ts处理这一点。

为什么Paraglide JS是SvelteKit的推荐i18n库?

Paraglide JS在构建时将消息文件编译为类型化的ESM函数。现代打包工具会对未使用的消息函数进行树摇优化,仅将当前语言的代码发送到浏览器。与运行时字典查找库相比,这样可以获得更小的打包体积。

SvelteKit通过Svelte CLI正式采用Paraglide JS作为其推荐的i18n解决方案。运行npx sv add paraglide会自动处理所有脚手架工作:Vite插件、inlang项目文件、钩子和示例消息文件夹。

其他库同样可用。Typesafe-i18n和svelte-i18n都是支持越南语的成熟选项。但对于新的SvelteKit项目,Paraglide是Svelte团队的官方推荐方案。

如何为SvelteKit中的越南语配置Paraglide JS?

配置分四步完成。所有文件应使用支持UTF-8的工具编辑,以保留越南语变音符号。

第一步 - 搭建脚手架:运行Svelte CLI命令创建完整项目结构:

npx sv add paraglide

此命令生成project.inlang/settings.json,将Vite插件连接到vite.config.ts,并创建messages/en.json作为基础语言文件。

第二步 - 添加越南语语言区域。在project.inlang/settings.json中,将vi添加到languageTags数组:

{ "languageTags": ["en", "vi"], "baseLocale": "en" }

第三步 - 创建messages/vi.json,使用相同消息ID填入越南语字符串。越南语变音符号必须以UTF-8 NFC规范化存储:

{ "greeting": "Xin chào, {name}!", "items_in_cart": "{count} sản phẩm trong giỏ hàng", "checkout_button": "Thanh toán" }

第四步 - 在src/hooks.server.ts中添加中间件,在src/hooks.ts中添加重路由钩子:

// hooks.server.ts
import type { Handle } from '@sveltejs/kit/hooks';
import { paraglideMiddleware } from '$lib/paraglide/server';
export const handle: Handle = ({ event, resolve }) =>
  paraglideMiddleware(event.request, ({ request: localizedRequest }) =>
    resolve({ ...event, request: localizedRequest }));

// hooks.ts
import type { Reroute } from '@sveltejs/kit/hooks';
import { deLocalizeUrl } from '$lib/paraglide/runtime';
export const reroute: Reroute = ({ url }) => deLocalizeUrl(url).pathname;

越南语格式化:日期、数字和货币

Paraglide负责显示哪个字符串。JavaScript的Intl API负责数字、日期和货币的显示方式。对这三者均使用vi-VN语言区域代码:

  • 日期:new Intl.DateTimeFormat('vi-VN', { dateStyle: 'short' }).format(date)返回DD/MM/YYYY格式。越南用户期望日期在前的顺序。
  • 数字:new Intl.NumberFormat('vi-VN').format(1500000)返回1.500.000。句点是千位分隔符,逗号是小数分隔符,与英语相反。
  • 货币(VND):new Intl.NumberFormat('vi-VN', { style: 'currency', currency: 'VND' }).format(250000)返回250.000 ₫。越南盾没有小数位。
  • 排序:越南语字母顺序与ASCII不同。对任何客户端排序的列表使用new Intl.Collator('vi').compare。越南语字母表有29个基本字母。

越南语字符串会带来哪些布局问题?

越南语字符串在UI标签和导航文本中通常比英语长10-20%。长度增加来自多音节词和没有英语对应词的语法助词。

在发布越南语SvelteKit应用之前,请检查以下列表:

  • 在375px和390px视口宽度下测试所有按钮文本和导航标签。
  • 验证字体覆盖:越南语使用六个声调符号的组合变音符。仅限基础拉丁字符的Web字体子集可能遗漏越南语字形。显式添加越南语Unicode范围:U+0102-0103, U+0110-0111, U+1EA0-1EF9。
  • 在根<html>元素上设置lang="vi"。SvelteKit的app.html模板支持Paraglide在请求时填充的%lang%占位符。
  • 在基础CSS中应用overflow-wrap: break-word。越南语文本在音节词之间的空格处断行,但长复合技术术语可能会溢出狭窄容器。
  • 将所有越南语字符串输入规范化为NFC。越南语变音符可以编码为NFC预合成或NFD分解形式,外观相同但字符串相等检查会失败。对任何用户输入的越南语文本使用str.normalize('NFC')。

内部处理还是聘请专家:越南语SvelteKit应用的真实分界线

技术工作,包括配置Paraglide、编写钩子、连接Intl,完全可以在内部完成。任何开发人员都可以按照Paraglide JS + SvelteKit官方指南在几个小时内完成路由层配置。对于大多数应用来说,机器翻译可以以可接受的质量处理结构化UI字符串,如错误消息、字段标签和帮助文本。

越南本地专家真正发挥作用的地方:产品UI语气、营销文案和特定领域术语。越南语区分正式语体(用于专业应用)和非正式语体(用于消费应用),选择错误会被越南用户察觉。汉越词汇在金融、医疗和法律产品中传达专业性,而通用机器翻译引擎默认使用纯越南语对应词,专家认为这不够精确。

实际分工:对长尾帮助文档使用机器翻译,对用户每次会话都会遇到的50-100个UI字符串委托人工审核。对于越南采购团队将评估产品的B2B产品,上线前需要由越南母语者审核完整界面。

如需专业的英语或中文到越南语的网站和SaaS界面本地化,本站的越南语网站本地化服务提供翻译和技术审校服务。

常见问题

越南语在Paraglide消息文件中需要特殊的Unicode规范化吗?

是的。越南语变音符可以编码为预合成NFC(每个字符一个码点)或分解NFD(基本字符加组合标记)形式。两者在浏览器中看起来相同,但字符串相等检查会失败。将所有越南语消息文件内容存储为NFC形式。在JavaScript中:str.normalize('NFC')。

在Paraglide中应使用'vi'还是'vi-VN'作为语言区域代码?

在Paraglide的languageTags和URL语言前缀中使用vi。根据W3C BCP 47指南,语言标签应尽可能简短。对于JavaScript的Intl API,vi-VN更明确,可确保一致的格式化数据查找,但vi在大多数格式化操作中同样有效。

Paraglide如何处理越南语复数消息?

越南语只有一个CLDR复数类别:other。所有数字都映射到other,因为越南语使用量词和语境来表达数量。ICU语法{count, plural, other {# sản phẩm}}覆盖所有数量。对于特定的零状态消息,仍可使用=0和=1精确匹配选择器。

SvelteKit中Paraglide的URL语言前缀如何工作?

Paraglide为所有URL添加语言前缀:越南语页面在/vi/路径下提供服务。hooks.ts中的reroute钩子会剥离语言前缀,让SvelteKit的基于文件的路由器看到未本地化的路径。hooks.server.ts中的paraglideMiddleware从URL前缀检测语言,并通过AsyncLocalStorage为当前请求设置语言。

可以将Paraglide JS与SvelteKit的静态适配器一起生成完全静态的越南语站点吗?

可以。Paraglide JS与@sveltejs/adapter-static兼容。在Paraglide Vite插件配置中设置strategy: ['url', 'baseLocale'],并预渲染所有语言变体。在静态适配器配置中添加entries: ['/vi/', '/en/', '/zh/', '/fr/'],让SvelteKit为每种语言生成HTML。编译后的消息函数是静态ESM,不需要运行时服务器。

参考来源

Dao Huy (Lucas)
Dao Huy (Lucas)
岘港大学外国语大学毕业。每份认证翻译均附签名的准确性声明(USCIS、IRCC)。

作者:Đào Huy(Lucas),越南语译员与本地化专家(英、中、法译越)。 See translation services →

报价WhatsApp