Render flags for languages, with custom upload for non-ISO locales

Standard locales now render real SVG flags (via country-flag-icons) in
the public LanguagePicker, the admin translation tabs, and the Lingue
settings page — replacing emoji that rendered as letter pairs on
Windows.

Custom locales (e.g. vec) keep the uppercase code-chip fallback by
default, and admins can now upload a per-locale flag image from the
Languages settings page. Uploads land in R2 under
images/settings/flag-<code>-*.{jpg,png,webp}, with old keys cleaned up
on re-upload and on delete.

Author: vekexasia

.pii-allowlist

@@ -5,6 +5,11 @@
 ^https?://(www\.)?keepachangelog\.com(/.*)?$
 ^https?://(www\.)?nextjs\.org(/.*)?$
 ^https?://github\.com/vekexasia/risto-menu(/.*)?$
+# RFC 2606 reserved example domains used in test fixtures.
+^https?://([a-z0-9-]+\.)*example\.(com|org|net)(/.*)?$
+# test.local fake hostname used in worker integration tests.
+^https?://test\.local(/.*)?$
+test\.local
 
 # ── Drizzle snapshot identifiers ──
 # drizzle generates a fresh UUID for each migration snapshot's `id`/`prevId`.
@@ -35,3 +40,6 @@
 (?i)^prosecco$
 (?i)^merlot$
 (?i)^carbonara$
+# Italian regions used in custom-locale fixtures (not personal names).
+(?i)^veneto$
+(?i)^v[èe]neto$

backend/src/__tests__/locale-flag.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createApp } from '../app';
+import { makeEnv } from './helpers';
+import { createTestDb, makeDbEnv, seedSettings, signTestJwt, installJwksMock } from './helpers/db';
+import type { Env } from '../types';
+
+beforeAll(() => installJwksMock());
+
+const ADMIN_UID = 'admin-1';
+
+type StoredObject = { body: ArrayBuffer; contentType?: string };
+
+function makeFakeBucket() {
+  const store = new Map<string, StoredObject>();
+  const bucket = {
+    async put(key: string, value: ArrayBuffer, opts?: { httpMetadata?: { contentType?: string } }) {
+      store.set(key, { body: value, contentType: opts?.httpMetadata?.contentType });
+      return { key };
+    },
+    async delete(key: string) {
+      store.delete(key);
+    },
+    async get(key: string) {
+      const o = store.get(key);
+      return o ? { body: o.body, httpMetadata: { contentType: o.contentType } } : null;
+    },
+    _store: store,
+  };
+  return bucket as unknown as R2Bucket & { _store: Map<string, StoredObject> };
+}
+
+function flagKeys(bucket: { _store: Map<string, StoredObject> }): string[] {
+  return Array.from(bucket._store.keys()).filter((k) => k.startsWith('images/settings/flag-'));
+}
+
+function makeJpeg(extraBytes = 100): ArrayBuffer {
+  const buf = new Uint8Array(3 + extraBytes);
+  buf[0] = 0xff; buf[1] = 0xd8; buf[2] = 0xff;
+  return buf.buffer;
+}
+
+async function adminEnv() {
+  const db = createTestDb();
+  seedSettings(db);
+  const bucket = makeFakeBucket();
+  const env = makeDbEnv(db, {
+    ADMIN_EMAILS: ADMIN_UID,
+    PUBLIC_MENU_BUCKET: bucket,
+    R2_PUBLIC_URL: 'https://cdn.example.com',
+  } as Partial<Env>);
+  const token = await signTestJwt(ADMIN_UID);
+  return { db, env, bucket, headers: { 'Cf-Access-Jwt-Assertion': token } };
+}
+
+async function fetchApp(path: string, init: RequestInit, env: Env): Promise<Response> {
+  const app = createApp();
+  return app.fetch(new Request(`https://test.local${path}`, init), env);
+}
+
+async function setCustomLocales(env: Env, headers: Record<string, string>, locales: { code: string; name: string; flagUrl?: string | null }[]) {
+  const res = await fetchApp('/admin/settings', {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify({ customLocales: locales }),
+  }, env);
+  expect(res.status).toBe(200);
+}
+
+describe('POST /admin/locale-flag/:code', () => {
+  it('uploads a flag and stores the URL on the matching custom locale', async () => {
+    const { env, headers, bucket } = await adminEnv();
+    await setCustomLocales(env, headers, [{ code: 'vec', name: 'Veneto' }]);
+
+    const res = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+
+    expect(res.status).toBe(200);
+    const body = await res.json() as { ok: true; flagUrl: string };
+    expect(body.flagUrl).toMatch(/^https:\/\/cdn\.example\.com\/images\/settings\/flag-vec-\d+\.jpg$/);
+    expect(flagKeys(bucket)).toHaveLength(1);
+
+    const settings = await fetchApp('/admin/settings', { method: 'GET', headers }, env);
+    const settingsBody = await settings.json() as { customLocales?: { code: string; flagUrl?: string }[] };
+    const vec = settingsBody.customLocales?.find((l) => l.code === 'vec');
+    expect(vec?.flagUrl).toBe(body.flagUrl);
+  });
+
+  it('rejects an invalid locale code', async () => {
+    const { env, headers } = await adminEnv();
+    const res = await fetchApp('/admin/locale-flag/UPPER', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 404 when the custom locale does not exist', async () => {
+    const { env, headers } = await adminEnv();
+    const res = await fetchApp('/admin/locale-flag/zzz', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+    expect(res.status).toBe(404);
+  });
+
+  it('rejects non-image bodies with 415', async () => {
+    const { env, headers } = await adminEnv();
+    await setCustomLocales(env, headers, [{ code: 'vec', name: 'Veneto' }]);
+    const garbage = new Uint8Array(16).fill(0xAB).buffer;
+    const res = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: garbage,
+    }, env);
+    expect(res.status).toBe(415);
+  });
+
+  it('deletes the previous R2 object on re-upload', async () => {
+    const { env, headers, bucket } = await adminEnv();
+    await setCustomLocales(env, headers, [{ code: 'vec', name: 'Veneto' }]);
+
+    const first = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+    expect(first.status).toBe(200);
+    expect(flagKeys(bucket)).toHaveLength(1);
+    const firstKey = flagKeys(bucket)[0];
+
+    await new Promise((r) => setTimeout(r, 2));
+
+    const second = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+    expect(second.status).toBe(200);
+    expect(flagKeys(bucket)).toHaveLength(1);
+    const secondKey = flagKeys(bucket)[0];
+    expect(secondKey).not.toBe(firstKey);
+  });
+
+  it('requires admin auth', async () => {
+    const db = createTestDb();
+    seedSettings(db);
+    const bucket = makeFakeBucket();
+    const env = makeDbEnv(db, {
+      ADMIN_EMAILS: 'someone-else',
+      PUBLIC_MENU_BUCKET: bucket,
+      R2_PUBLIC_URL: 'https://cdn.example.com',
+    } as Partial<Env>);
+    void makeEnv;
+
+    const res = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg' },
+      body: makeJpeg(),
+    }, env);
+    expect([401, 403]).toContain(res.status);
+  });
+});
+
+describe('DELETE /admin/locale-flag/:code', () => {
+  it('clears flagUrl and removes the R2 object', async () => {
+    const { env, headers, bucket } = await adminEnv();
+    await setCustomLocales(env, headers, [{ code: 'vec', name: 'Veneto' }]);
+
+    const upload = await fetchApp('/admin/locale-flag/vec', {
+      method: 'POST',
+      headers: { 'Content-Type': 'image/jpeg', ...headers },
+      body: makeJpeg(),
+    }, env);
+    expect(upload.status).toBe(200);
+    expect(flagKeys(bucket)).toHaveLength(1);
+
+    const del = await fetchApp('/admin/locale-flag/vec', { method: 'DELETE', headers }, env);
+    expect(del.status).toBe(200);
+    expect(flagKeys(bucket)).toHaveLength(0);
+
+    const settings = await fetchApp('/admin/settings', { method: 'GET', headers }, env);
+    const body = await settings.json() as { customLocales?: { code: string; flagUrl?: string | null }[] };
+    expect(body.customLocales?.find((l) => l.code === 'vec')?.flagUrl ?? null).toBeNull();
+  });
+});

backend/src/db/schema.ts

@@ -59,7 +59,7 @@ export const settings = sqliteTable('settings', {
   aiChatEnabled: integer('ai_chat_enabled', { mode: 'boolean' }).default(false).notNull(),
   enabledLocales: jsonColumn<string[] | null>('enabled_locales'),
   disabledLocales: jsonColumn<string[] | null>('disabled_locales'),
-  customLocales: jsonColumn<{ code: string; name: string }[] | null>('custom_locales'),
+  customLocales: jsonColumn<{ code: string; name: string; flagUrl?: string | null }[] | null>('custom_locales'),
   publicationState: text('publication_state').default('draft').notNull(),
   ...timestamps,
 });

backend/src/routes/admin.ts

@@ -586,6 +586,73 @@ admin.post('/promotion-image', ...base, async (c) => {
   return c.json({ ok: true, imageUrl: upload.imageUrl });
 });
 
+admin.post('/locale-flag/:code', ...base, async (c) => {
+  const code = c.req.param('code');
+  if (!/^[a-z0-9-]{2,10}$/.test(code)) {
+    return c.json({ error: 'Invalid locale code' }, 400);
+  }
+
+  const db = c.get('db');
+  const [row] = await db
+    .select({ customLocales: schema.settings.customLocales })
+    .from(schema.settings)
+    .where(eq(schema.settings.id, 1))
+    .limit(1);
+  const list = row?.customLocales ?? [];
+  const target = list.find((l) => l.code === code);
+  if (!target) return c.json({ error: 'Custom locale not found' }, 404);
+
+  const upload = await uploadSettingsImage(c, `flag-${code}`);
+  if ('response' in upload) return upload.response;
+
+  const bucket = c.env.PUBLIC_MENU_BUCKET;
+  if (target.flagUrl && bucket) {
+    const oldKey = r2KeyFromUrl(target.flagUrl);
+    if (oldKey) await bucket.delete(oldKey);
+  }
+
+  const updated = list.map((l) => l.code === code ? { ...l, flagUrl: upload.imageUrl } : l);
+  await db
+    .update(schema.settings)
+    .set({ customLocales: updated, updatedAt: Date.now() })
+    .where(eq(schema.settings.id, 1));
+
+  await refreshPublicCatalog(c);
+  return c.json({ ok: true, flagUrl: upload.imageUrl });
+});
+
+admin.delete('/locale-flag/:code', ...base, async (c) => {
+  const code = c.req.param('code');
+  if (!/^[a-z0-9-]{2,10}$/.test(code)) {
+    return c.json({ error: 'Invalid locale code' }, 400);
+  }
+
+  const db = c.get('db');
+  const [row] = await db
+    .select({ customLocales: schema.settings.customLocales })
+    .from(schema.settings)
+    .where(eq(schema.settings.id, 1))
+    .limit(1);
+  const list = row?.customLocales ?? [];
+  const target = list.find((l) => l.code === code);
+  if (!target) return c.json({ error: 'Custom locale not found' }, 404);
+
+  const bucket = c.env.PUBLIC_MENU_BUCKET;
+  if (target.flagUrl && bucket) {
+    const oldKey = r2KeyFromUrl(target.flagUrl);
+    if (oldKey) await bucket.delete(oldKey);
+  }
+
+  const updated = list.map((l) => l.code === code ? { ...l, flagUrl: null } : l);
+  await db
+    .update(schema.settings)
+    .set({ customLocales: updated, updatedAt: Date.now() })
+    .where(eq(schema.settings.id, 1));
+
+  await refreshPublicCatalog(c);
+  return c.json({ ok: true });
+});
+
 // ── Analytics ────────────────────────────────────────────────────────
 
 admin.get('/analytics', ...base, async (c) => {

package-lock.json

@@ -15,7 +15,7 @@ export const UpdateSettingsBodySchema = z.object({
   aiChatEnabled: z.boolean().optional(),
   enabledLocales: z.array(z.string()).nullable().optional(),
   disabledLocales: z.array(z.string()).nullable().optional(),
-  customLocales: z.array(z.object({ code: z.string().min(2).max(10).regex(/^[a-z0-9-]+$/), name: z.string().min(1).max(50) })).nullable().optional(),
+  customLocales: z.array(z.object({ code: z.string().min(2).max(10).regex(/^[a-z0-9-]+$/), name: z.string().min(1).max(50), flagUrl: z.string().url().nullable().optional() })).nullable().optional(),
 });
 export type UpdateSettingsBody = z.infer<typeof UpdateSettingsBodySchema>;
 

packages/schemas/src/admin.ts

@@ -98,7 +98,7 @@ export const CatalogRestaurantSchema = z.object({
     aiChat: z.boolean(),
     enabledLocales: z.array(z.string()).nullable().optional(),
     disabledLocales: z.array(z.string()).nullable().optional(),
-    customLocales: z.array(z.object({ code: z.string(), name: z.string() })).nullable().optional(),
+    customLocales: z.array(z.object({ code: z.string(), name: z.string(), flagUrl: z.string().nullable().optional() })).nullable().optional(),
   }).optional(),
 });
 export type CatalogRestaurant = z.infer<typeof CatalogRestaurantSchema>;

packages/schemas/src/catalog.ts

@@ -27,7 +27,9 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@headlessui/react": "^2.2.9",
     "@hookform/resolvers": "^5.2.2",
+    "@menu/schemas": "*",
     "clsx": "^2.1.1",
+    "country-flag-icons": "^1.6.16",
     "date-fns": "^4.1.0",
     "framer-motion": "^12.25.0",
     "next": "^16.1.1",
@@ -38,8 +40,7 @@
     "react-intersection-observer": "^10.0.0",
     "tailwind-merge": "^3.4.0",
     "zod": "^4.3.5",
-    "zustand": "^5.0.9",
-    "@menu/schemas": "*"
+    "zustand": "^5.0.9"
   },
   "devDependencies": {
     "@opennextjs/cloudflare": "^1.0.0",