💡 要将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,不需要运行时服务器。
参考来源
- Paraglide JS:SvelteKit集成指南 - 官方配置文档:npx sv add paraglide、hooks.server.ts中间件、Vite插件配置。已于2026年11月验证。
- Unicode CLDR:语言复数规则 - 越南语的CLDR复数类别(单一"other"类别)。已于2026年11月验证。
- W3C国际化:选择语言标签 - 越南语vi与vi-VN的BCP 47指南。已于2026年11月验证。
- Google Search Central:本地化版本 - 多语言SvelteKit站点的hreflang要求。已于2026年11月验证。
作者:Đào Huy(Lucas),越南语译员与本地化专家(英、中、法译越)。 See translation services →

