Found me on Upwork? If you found me through Upwork and want to work together, please contact me through Upwork. Messages from Upwork clients sent outside Upwork will not be answered.
Localization notes🌏 Localization

SvelteKit Vietnamese Localization: Paraglide JS Setup and ICU Messages

Localize a SvelteKit app into Vietnamese with Paraglide JS: scaffold in one command, wire hooks middleware, and handle ICU messages with its single plural category.

Dao Huy (Lucas)7 min read8 sections
SvelteKit Vietnamese Localization: Paraglide JS Setup and ICU Messages

💡 To localize a SvelteKit app into Vietnamese with Paraglide JS: run npx sv add paraglide, list vi in your inlang project locales, add the middleware to hooks.server.ts, and import typed message functions. Vietnamese has one ICU plural category (other), so plural strings need only a single branch. Expect strings to run 10-20% longer than English equivalents.

Key takeaways

  • Run npx sv add paraglide to scaffold the full Paraglide JS + SvelteKit setup in one command. The CLI creates project.inlang/settings.json, a messages/ folder, and wires the Vite plugin automatically.
  • Add vi to the languageTags array in project.inlang/settings.json. Create messages/vi.json with Vietnamese translations keyed to the same message IDs as your base locale.
  • Vietnamese has one CLDR plural category: other. All ICU plural messages simplify to a single branch - never requiring a separate one form.
  • Use the paraglideMiddleware in hooks.server.ts and the deLocalizeUrl reroute hook in hooks.ts for locale-prefixed URLs and correct SSR locale injection.
  • Vietnamese strings typically run 10-20% longer than English. Test all button labels and navigation items at 375px and 390px viewports. Web font subsets must include the full Vietnamese Unicode block (U+1EA0-U+1EF9).

What does SvelteKit Vietnamese localization actually require?

Localizing a SvelteKit app into Vietnamese involves four distinct concerns: message management, locale routing, number and date formatting, and layout testing. These are independent problems, and you can solve each one without the others blocking you.

Paraglide JS handles message management and locale routing. The JavaScript Intl API handles formatting with the vi-VN locale. Layout testing is a manual step that reveals font and string-length issues unique to Vietnamese.

SvelteKit's server-side rendering adds one requirement: the locale must be detected per-request on the server and passed to the client. Paraglide's middleware handles this via hooks.server.ts.

Paraglide JS compiles your message files into typed ESM functions at build time. Modern bundlers then tree-shake unused message functions so only the active locale's code ships to the browser. The result is smaller bundles compared to runtime dictionary libraries.

SvelteKit officially adopted Paraglide JS as its recommended i18n solution via the Svelte CLI. Running npx sv add paraglide handles the entire scaffold automatically: the Vite plugin, the inlang project file, the hooks, and a sample messages folder.

Alternative libraries still work. Typesafe-i18n and svelte-i18n are mature options with Vietnamese support. But for new SvelteKit projects, Paraglide is the first-party recommendation backed by the Svelte team.

How do you configure Paraglide JS for Vietnamese in SvelteKit?

The setup takes four steps. All files should be edited with a UTF-8-safe tool to preserve Vietnamese diacritics correctly.

Step 1 - Scaffold: Run the Svelte CLI addon command to generate the full project structure:

npx sv add paraglide

This generates project.inlang/settings.json, wires the Vite plugin into vite.config.ts, and creates messages/en.json as the base locale file.

Step 2 - Add the Vietnamese locale. In project.inlang/settings.json, add vi to the languageTags array:

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

Step 3 - Create messages/vi.json with your Vietnamese strings. Use the same message IDs as your base locale file. Vietnamese diacritics must be stored as UTF-8 NFC-normalized characters:

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

Step 4 - Add the middleware to src/hooks.server.ts and the reroute hook to 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;

Vietnamese formatting: dates, numbers, and currency with Intl

Paraglide handles which string to show. The JavaScript Intl API handles how numbers, dates, and currency render. Use locale code vi-VN for all three:

  • Dates: new Intl.DateTimeFormat('vi-VN', { dateStyle: 'short' }).format(date) returns DD/MM/YYYY. Vietnamese users expect day-first ordering.
  • Numbers: new Intl.NumberFormat('vi-VN').format(1500000) returns 1.500.000. Period is the thousands separator; comma is the decimal separator - the opposite of English.
  • Currency (VND): new Intl.NumberFormat('vi-VN', { style: 'currency', currency: 'VND' }).format(250000) returns 250.000 ₫. VND has no decimal subdivision.
  • Sorting: Vietnamese alphabetical order differs from ASCII. Use new Intl.Collator('vi').compare for any list sorted client-side. The Vietnamese alphabet has 29 base letters with distinct collation rules.

What layout issues should you expect with Vietnamese strings?

Vietnamese strings typically run 10-20% longer than English equivalents in UI labels and navigation text. The length increase comes from polysyllabic terms and grammatical particles that have no English counterpart.

Run through this checklist before launching your Vietnamese SvelteKit app:

  • Test all button text and navigation labels at 375px and 390px viewport widths.
  • Verify font coverage: Vietnamese uses combining diacritics across six tone marks plus hook and breve modifications. Web font subsets restricted to basic Latin (U+0020-U+007E) drop Vietnamese glyphs. Add the Vietnamese Unicode ranges explicitly: U+0102-0103, U+0110-0111, U+1EA0-1EF9.
  • Set lang="vi" on the root <html> element. SvelteKit's app.html template supports a %lang% placeholder that Paraglide fills at request time.
  • Apply overflow-wrap: break-word in your base CSS. Vietnamese text wraps at spaces between syllable-words, but long compound technical terms can overflow narrow containers.
  • Normalize all Vietnamese string inputs to NFC. Vietnamese diacritics can be encoded as precomposed NFC or decomposed NFD - visually identical but failing string equality checks. Use str.normalize('NFC') on any user-generated Vietnamese text.

In-house vs specialist: the honest line for Vietnamese SvelteKit apps

The engineering work - scaffolding Paraglide, writing hooks, wiring Intl - is completely in-house. Any developer can follow the official Paraglide JS + SvelteKit guide and have the routing layer running in a few hours. Machine translation handles structured UI strings like error messages, field labels, and help text with acceptable quality for most apps.

Where a native Vietnamese specialist makes a real difference: product UI tone, marketing copy, and domain-specific terminology. Vietnamese distinguishes formal register (used in professional apps) from informal register (used in consumer apps), and the wrong choice reads as unprofessional to Vietnamese users. Sino-Vietnamese vocabulary signals expertise in finance, healthcare, and legal products - generic MT engines default to plain Vietnamese equivalents that specialists find imprecise.

The practical split: use MT for the long tail of help documentation, and commission a human reviewer for the 50-100 UI strings a user encounters in every session. For B2B products where a Vietnamese procurement team will evaluate the product, have a native speaker audit the full UI before launch.

For professional English-to-Vietnamese website and SaaS UI localization, the Vietnamese website localization service on this site covers both translation and technical review.

FAQ

Does Vietnamese require any special Unicode normalization in Paraglide message files?

Yes. Vietnamese diacritics can be encoded as precomposed NFC (one code point per character) or decomposed NFD (base character plus combining marks). Both render identically in the browser but fail string equality checks. Store all Vietnamese message file content as NFC. In JavaScript: str.normalize('NFC'). Most editors default to NFC, but check if you paste strings from external tools.

Should I use 'vi' or 'vi-VN' as the locale code in Paraglide?

Use vi in your Paraglide languageTags and for the URL locale prefix. Per W3C BCP 47 guidance, keep language tags as short as possible unless you need to distinguish regional variants. For the JavaScript Intl API, vi-VN is more explicit and ensures consistent formatting data lookup, but vi works for most formatting operations.

How does Paraglide handle Vietnamese plural messages?

Vietnamese has one CLDR plural category: other. All numbers map to other because Vietnamese expresses quantity through noun classifiers and context, not morphological plural forms. The ICU syntax {count, plural, other {# sản phẩm}} covers all quantities. You can still use =0 and =1 exact-match selectors for specific zero-state messages.

How do locale-prefixed URLs work with Paraglide in SvelteKit?

Paraglide adds a locale prefix to all URLs: your Vietnamese pages are served at /vi/your-route. The reroute hook in hooks.ts strips the locale prefix so SvelteKit's file-based router sees the unlocalized path. The paraglideMiddleware in hooks.server.ts detects the locale from the URL prefix and sets it for the current request via AsyncLocalStorage. No manual locale extraction is needed in page components.

Can I use Paraglide JS with SvelteKit's static adapter for a fully static Vietnamese site?

Yes. Paraglide JS works with @sveltejs/adapter-static. Set strategy: ['url', 'baseLocale'] in the Paraglide Vite plugin config and prerender all locale variants. Add entries: ['/vi/', '/en/', '/zh/', '/fr/'] to your static adapter config so SvelteKit generates HTML for each locale. The compiled message functions are static ESM and require no runtime server.

Official Sources

Dao Huy (Lucas)
Dao Huy (Lucas)
Graduate, University of Foreign Language Studies, University of Da Nang. Signs a certificate of accuracy on every certified translation (USCIS, IRCC).

Written by Dao Huy (Lucas), Vietnamese translator and localization specialist (English, Chinese and French into Vietnamese). See translation services →

Get QuoteWhatsApp