[Maintainer] i18n: locale registry, formatting and first locales

.github/workflows/ci.yml

@@ -80,6 +80,9 @@ jobs:
       - name: Lint & format check
         run: bun run check
 
+      - name: Check localization catalogs
+        run: bun run i18n:check
+
       - name: Validate agent skills and plugin packages
         if: needs.changes.outputs.skills == 'true' || github.event_name == 'push'
         run: bun run skills:validate

AGENTS.md

@@ -29,7 +29,7 @@ Public, open-source home of `@pascal-app/{core,viewer,editor,nodes,mcp,cli,ifc-c
 
 ## Commands
 
-`bun run ci` is exactly what CI runs (check, skills:validate, check-types, test, build). The git hooks (installed by `bun install`) are fast feedback: Biome on staged files, typecheck of the packages you changed.
+`bun run ci` is exactly what CI runs (check, i18n:check, skills:validate, check-types, test, build). Localization catalog and language-pack guidance lives in `i18n/README.md`. The git hooks (installed by `bun install`) are fast feedback: Biome on staged files, typecheck of the packages you changed.
 
 ## Working agreements
 

apps/editor/app/client-bootstrap.tsx

@@ -9,18 +9,39 @@
 // `loaded` guard inside `../lib/bootstrap` keeps the side effect
 // idempotent under HMR.
 import '../lib/bootstrap'
-import { type ReactNode, useEffect } from 'react'
+import { createI18n, defaultI18n, PascalI18nProvider } from '@pascal-app/core'
+import { registerBundledLocales } from '@pascal-app/editor/locales'
+import { type ReactNode, useEffect, useMemo } from 'react'
+
+registerBundledLocales()
 
 export function ClientBootstrap({
   children,
   enableDevDiagnostics,
+  locale,
 }: {
   children: ReactNode
   enableDevDiagnostics: boolean
+  locale: string
 }) {
+  const i18n = useMemo(() => createI18n({ locale }), [locale])
+
   useEffect(() => {
     if (!enableDevDiagnostics) return
     import('react-scan').then(({ scan }) => scan({ enabled: true }))
   }, [enableDevDiagnostics])
-  return children
+
+  useEffect(() => {
+    const syncDocumentLocale = () => {
+      document.documentElement.lang = i18n.getLocale()
+    }
+    syncDocumentLocale()
+    return i18n.subscribe(syncDocumentLocale)
+  }, [i18n])
+
+  useEffect(() => {
+    return defaultI18n.subscribeLocale((nextLocale) => i18n.setLocale(nextLocale))
+  }, [i18n])
+
+  return <PascalI18nProvider i18n={i18n}>{children}</PascalI18nProvider>
 }

apps/editor/app/layout.tsx

@@ -1,10 +1,15 @@
+import { registerBundledLocales } from '@pascal-app/editor/locales'
 import { Agentation } from 'agentation'
 import { GeistPixelSquare } from 'geist/font/pixel'
 import { Barlow } from 'next/font/google'
 import localFont from 'next/font/local'
+import { headers } from 'next/headers'
+import { PASCAL_LOCALE_HEADER, resolveUiLocale } from '@/lib/ui-locale'
 import { ClientBootstrap } from './client-bootstrap'
 import './globals.css'
 
+registerBundledLocales()
+
 const geistSans = localFont({
   src: './fonts/GeistVF.woff',
   variable: '--font-geist-sans',
@@ -21,21 +26,24 @@ const barlow = Barlow({
   display: 'swap',
 })
 
-export default function RootLayout({
+export default async function RootLayout({
   children,
 }: Readonly<{
   children: React.ReactNode
 }>) {
   const enableDevDiagnostics =
     process.env.NODE_ENV === 'development' && process.env.PASCAL_DEV_DIAGNOSTICS === '1'
+  const locale = resolveUiLocale((await headers()).get(PASCAL_LOCALE_HEADER))
 
   return (
     <html
       className={`${geistSans.variable} ${geistMono.variable} ${GeistPixelSquare.variable} ${barlow.variable}`}
-      lang="en"
+      lang={locale}
     >
       <body className="font-sans">
-        <ClientBootstrap enableDevDiagnostics={enableDevDiagnostics}>{children}</ClientBootstrap>
+        <ClientBootstrap enableDevDiagnostics={enableDevDiagnostics} locale={locale}>
+          {children}
+        </ClientBootstrap>
         {enableDevDiagnostics && <Agentation />}
       </body>
     </html>

apps/editor/lib/ui-locale.ts

@@ -0,0 +1,11 @@
+export const PASCAL_LOCALE_HEADER = 'x-pascal-locale'
+
+export function resolveUiLocale(value: string | null | undefined): string {
+  const requested = value?.trim()
+  if (!requested) return 'en'
+  try {
+    return Intl.getCanonicalLocales(requested)[0] ?? 'en'
+  } catch {
+    return 'en'
+  }
+}

apps/editor/proxy.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, expect, test } from 'bun:test'
+import { readdirSync } from 'node:fs'
 import { unstable_doesMiddlewareMatch } from 'next/experimental/testing/server'
 import { issueSession, SESSION_COOKIE } from './lib/self-host-auth'
+import { resolveUiLocale } from './lib/ui-locale'
 import { config, gateRequest } from './proxy'
 
 const OLD_ENV = { ...process.env }
@@ -31,10 +33,10 @@ test('an unconfigured network host sends pages to setup and APIs to 503', async
 test('a password gates pages behind login and keeps the requested path', () => {
   process.env.PASCAL_ADMIN_PASSWORD = 'secret'
 
-  const response = gateRequest(request('/project/abc?tab=build'))
+  const response = gateRequest(request('/project/abc?tab=build&lang=fr'))
   expect(response?.status).toBe(307)
   expect(response?.headers.get('location')).toBe(
-    'https://pascal.example/login?next=%2Fproject%2Fabc%3Ftab%3Dbuild',
+    'https://pascal.example/login?next=%2Fproject%2Fabc%3Ftab%3Dbuild%26lang%3Dfr',
   )
   expect(gateRequest(request('/api/plugins/mint/session'))?.status).toBe(401)
 })
@@ -107,6 +109,25 @@ test('Next and public/ static assets skip the proxy', () => {
   }
 })
 
+test('the proxy exclusion list stays aligned with public/ and app/ folders', () => {
+  const topLevelFolders = (relativePath: string) =>
+    readdirSync(new URL(relativePath, import.meta.url), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort()
+  const publicFolders = topLevelFolders('./public/')
+  const appFolders = topLevelFolders('./app/')
+
+  for (const folder of publicFolders) {
+    const path = `/${folder}/__proxy-drift-check__`
+    expect([folder, unstable_doesMiddlewareMatch({ config, url: path })]).toEqual([folder, false])
+  }
+  for (const folder of appFolders.filter((folder) => !publicFolders.includes(folder))) {
+    const path = `/${folder}/__proxy-drift-check__`
+    expect([folder, unstable_doesMiddlewareMatch({ config, url: path })]).toEqual([folder, true])
+  }
+})
+
 test('loopback and an upstream proxy are open', () => {
   delete process.env.PASCAL_ADMIN_PASSWORD
   const loopback = new Request('http://localhost:3002/', {
@@ -116,3 +137,10 @@ test('loopback and an upstream proxy are open', () => {
   process.env.PASCAL_AUTH = 'proxy'
   expect(gateRequest(request('/'))).toBeNull()
 })
+
+test('UI locale canonicalization is deterministic for server rendering', () => {
+  expect(resolveUiLocale('fr')).toBe('fr')
+  expect(resolveUiLocale('zh-hans-cn')).toBe('zh-Hans-CN')
+  expect(resolveUiLocale('')).toBe('en')
+  expect(resolveUiLocale('not_a_locale')).toBe('en')
+})

apps/editor/proxy.ts

@@ -1,5 +1,6 @@
 import { type NextRequest, NextResponse } from 'next/server'
 import { resolveAuthMode, sessionPrincipal } from '@/lib/self-host-auth'
+import { PASCAL_LOCALE_HEADER, resolveUiLocale } from '@/lib/ui-locale'
 
 /**
  * Self-host gate. Pages redirect to `/login` (or `/setup` when nothing is
@@ -17,7 +18,12 @@ const OPEN_PREFIXES = ['/embed/']
 const SELF_GUARDED_API_PREFIXES = ['/api/scenes', '/api/artifacts']
 
 export function proxy(request: NextRequest) {
-  return gateRequest(request) ?? NextResponse.next()
+  const gated = gateRequest(request)
+  if (gated) return gated
+
+  const headers = new Headers(request.headers)
+  headers.set(PASCAL_LOCALE_HEADER, resolveUiLocale(request.nextUrl.searchParams.get('lang')))
+  return NextResponse.next({ request: { headers } })
 }
 
 export function gateRequest(request: Request): NextResponse | null {

biome.jsonc

@@ -118,6 +118,8 @@
       "!**/build",
       "!**/public",
       "!**/components/ui",
+      // Generated by `lingui compile`; source of truth is the adjacent PO file.
+      "!packages/editor/src/i18n/locales/**/messages.ts",
       // Recorded API responses; kept byte-exact.
       "!**/__fixtures__",
       "!**/next-env.d.ts"