From a50e003719774b4bec1d179867d27df2333a231e Mon Sep 17 00:00:00 2001
From: Ailton Heusser Junior <ailton.eleveia@gmail.com>
Date: Sat, 12 Sep 2026 07:30:13 -0300
Subject: [PATCH] feat: add Brazilian Portuguese localization foundation

Signed-off-by: Ailton Heusser Junior <ailton.eleveia@gmail.com>
---
 package.json                              |   2 +
 pnpm-lock.yaml                            |  50 +++++++
 src/app/LanguageSettings.tsx              |  49 +++++++
 src/app/Settings.tsx                      |  21 ++-
 src/app/navigation.ts                     |   2 +-
 src/app/shell/AppShell.tsx                |  11 +-
 src/app/shell/Home.tsx                    |  17 ++-
 src/app/shell/PageSearch.tsx              |  26 ++--
 src/app/shell/ProfileButton.tsx           |  12 +-
 src/features/localization/service.test.ts |  35 +++++
 src/features/localization/service.ts      | 153 ++++++++++++++++++++++
 tests/browser/settings.spec.mjs           |  34 +++++
 12 files changed, 381 insertions(+), 31 deletions(-)
 create mode 100644 src/app/LanguageSettings.tsx
 create mode 100644 src/features/localization/service.test.ts
 create mode 100644 src/features/localization/service.ts

diff --git a/package.json b/package.json
index ec19fb25..d101aa77 100644
--- a/package.json
+++ b/package.json
@@ -48,11 +48,13 @@
     "dockview-react": "8.2.0",
     "emoji-mart": "5.6.0",
     "flexlayout-react": "0.10.8",
+    "i18next": "^26.4.2",
     "lucide-react": "1.34.0",
     "mdast-util-from-markdown": "2.0.3",
     "nostr-tools": "2.25.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
+    "react-i18next": "^17.0.13",
     "react-markdown": "10.1.0",
     "remark-breaks": "4.0.0",
     "remark-gfm": "4.0.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bad39e68..9435fe4c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -47,6 +47,9 @@ importers:
       flexlayout-react:
         specifier: 0.10.8
         version: 0.10.8(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      i18next:
+        specifier: ^26.4.2
+        version: 26.4.2(typescript@7.0.2)
       lucide-react:
         specifier: 1.34.0
         version: 1.34.0(react@19.2.8)
@@ -62,6 +65,9 @@ importers:
       react-dom:
         specifier: 19.2.8
         version: 19.2.8(react@19.2.8)
+      react-i18next:
+        specifier: ^17.0.13
+        version: 17.0.13(i18next@26.4.2(typescript@7.0.2))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(typescript@7.0.2)
       react-markdown:
         specifier: 10.1.0
         version: 10.1.0(@types/react@19.2.18)(react@19.2.8)
@@ -950,9 +956,20 @@ packages:
   hast-util-whitespace@3.0.0:
     resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
 
+  html-parse-stringify@4.0.1:
+    resolution: {integrity: sha512-0zHsZJrK7S3K2aucXWL6ycoYJ/iNtIcFHC/nYQgFklPtrv5LpJctIiSCroWZWeuoXvuyFdzp6KzjJQ+OT5MfFw==}
+
   html-url-attributes@3.0.1:
     resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
 
+  i18next@26.4.2:
+    resolution: {integrity: sha512-RX+R0VLg13IbvRuJSxnqykUFS9vQZTl8wYpWPCIUDWVrSGjsQywB5Y+pjzrkboxGAuYfJZVH1InFTdgBdxq6ug==}
+    peerDependencies:
+      typescript: ^5 || ^6 || ^7
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   inline-style-parser@0.2.7:
     resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
 
@@ -1332,6 +1349,22 @@ packages:
     peerDependencies:
       react: ^19.2.8
 
+  react-i18next@17.0.13:
+    resolution: {integrity: sha512-Cc1PscmblIHA1kljTqDwrcVMI21ydgmUzw0UAeQBe7pAOgfuRLfzXze4EUBQoeDiICzFIXXhHFoZxuetNg5D0Q==}
+    peerDependencies:
+      i18next: '>= 26.2.0'
+      react: '>= 16.8.0'
+      react-dom: '*'
+      react-native: '*'
+      typescript: ^5 || ^6 || ^7
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+      typescript:
+        optional: true
+
   react-markdown@10.1.0:
     resolution: {integrity: sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==}
     peerDependencies:
@@ -2202,8 +2235,14 @@ snapshots:
     dependencies:
       '@types/hast': 3.0.5
 
+  html-parse-stringify@4.0.1: {}
+
   html-url-attributes@3.0.1: {}
 
+  i18next@26.4.2(typescript@7.0.2):
+    optionalDependencies:
+      typescript: 7.0.2
+
   inline-style-parser@0.2.7: {}
 
   is-alphabetical@2.0.1: {}
@@ -2739,6 +2778,17 @@ snapshots:
       react: 19.2.8
       scheduler: 0.27.0
 
+  react-i18next@17.0.13(i18next@26.4.2(typescript@7.0.2))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(typescript@7.0.2):
+    dependencies:
+      '@babel/runtime': 7.29.7
+      html-parse-stringify: 4.0.1
+      i18next: 26.4.2(typescript@7.0.2)
+      react: 19.2.8
+      use-sync-external-store: 1.6.0(react@19.2.8)
+    optionalDependencies:
+      react-dom: 19.2.8(react@19.2.8)
+      typescript: 7.0.2
+
   react-markdown@10.1.0(@types/react@19.2.18)(react@19.2.8):
     dependencies:
       '@types/hast': 3.0.5
diff --git a/src/app/LanguageSettings.tsx b/src/app/LanguageSettings.tsx
new file mode 100644
index 00000000..f20743bd
--- /dev/null
+++ b/src/app/LanguageSettings.tsx
@@ -0,0 +1,49 @@
+import { useTranslation } from "react-i18next";
+import {
+  appLocales,
+  currentLocale,
+  setAppLocale,
+  type AppLocale,
+} from "../features/localization/service";
+
+export function LanguageSettings() {
+  const { t } = useTranslation();
+  return (
+    <section aria-labelledby="language-settings-title">
+      <h2
+        id="language-settings-title"
+        className="mt-0 mb-3 text-lg font-medium"
+      >
+        {t("language.title")}
+      </h2>
+      <div className="ui-card p-5 sm:p-6">
+        <label
+          htmlFor="application-language"
+          className="mb-2 block text-base font-medium"
+        >
+          {t("language.label")}
+        </label>
+        <p id="language-description" className="mt-0 mb-4 text-sm text-muted">
+          {t("language.description")}
+        </p>
+        <select
+          id="application-language"
+          aria-describedby="language-description"
+          value={currentLocale()}
+          onChange={(event) =>
+            void setAppLocale(event.currentTarget.value as AppLocale)
+          }
+          className="w-full max-w-sm rounded-xl border border-line bg-surface px-3 py-2 text-ink"
+        >
+          {appLocales.map((locale) => (
+            <option key={locale} value={locale}>
+              {locale === "pt-BR"
+                ? t("language.portugueseBrazil")
+                : t("language.english")}
+            </option>
+          ))}
+        </select>
+      </div>
+    </section>
+  );
+}
diff --git a/src/app/Settings.tsx b/src/app/Settings.tsx
index 5fdba59f..5ec386be 100644
--- a/src/app/Settings.tsx
+++ b/src/app/Settings.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useState, useSyncExternalStore } from "react";
 import { RecoveryScreen } from "./RecoveryScreen";
-import { Blocks, Settings2, UserRound, Palette } from "lucide-react";
+import { Blocks, Settings2, UserRound, Palette, Languages } from "lucide-react";
 import type { PluginManager } from "../plugins/manager";
 import type { Communities } from "../features/communities/service";
 import { PluginImport } from "./PluginImport";
@@ -8,11 +8,14 @@ import { ProfileSettings } from "./ProfileSettings";
 
 import type { Appearance } from "../shared/theme/service";
 import { AppearanceSettings } from "./AppearanceSettings";
+import { LanguageSettings } from "./LanguageSettings";
+import { useTranslation } from "react-i18next";
 
 const sections = [
-  { id: "profile", label: "Profile", icon: UserRound },
-  { id: "plugins", label: "Plugins", icon: Blocks },
-  { id: "appearance", label: "Appearance", icon: Palette },
+  { id: "profile", label: "settings.profile", icon: UserRound },
+  { id: "plugins", label: "settings.plugins", icon: Blocks },
+  { id: "appearance", label: "settings.appearance", icon: Palette },
+  { id: "language", label: "settings.language", icon: Languages },
 ] as const;
 
 export function Settings({
@@ -30,6 +33,7 @@ export function Settings({
     | undefined;
   onSection?: (section: string) => void;
 }) {
+  const { t } = useTranslation();
   const [selected, setSelected] =
     useState<(typeof sections)[number]["id"]>("profile");
   const requestedSection =
@@ -63,13 +67,13 @@ export function Settings({
             id="settings-title"
             className="m-0 text-3xl font-medium tracking-tight"
           >
-            Settings
+            {t("settings.title")}
           </h1>
         </div>
       </div>
       <div className="grid gap-6 @min-[36rem]:grid-cols-[10rem_minmax(0,1fr)]">
         <nav
-          aria-label="Settings sections"
+          aria-label={t("settings.sections")}
           className="flex flex-wrap gap-1 self-start rounded-2xl border border-shell-edge/80 bg-surface/60 p-2 @min-[36rem]:flex-col"
         >
           {sections.map(({ id, label, icon: Icon }) => (
@@ -85,7 +89,7 @@ export function Settings({
               }}
             >
               <Icon aria-hidden="true" size={18} strokeWidth={1.6} />
-              {label}
+              {t(label)}
             </button>
           ))}
         </nav>
@@ -96,6 +100,9 @@ export function Settings({
           <div hidden={selected !== "profile"}>
             <ProfileSettings communities={communities} />
           </div>
+          <div hidden={selected !== "language"}>
+            <LanguageSettings />
+          </div>
           <div hidden={selected !== "plugins"}>
             <section aria-labelledby="plugin-settings-title">
               <h2
diff --git a/src/app/navigation.ts b/src/app/navigation.ts
index 2a885c01..35a70426 100644
--- a/src/app/navigation.ts
+++ b/src/app/navigation.ts
@@ -77,7 +77,7 @@ export function useAppNavigation(services: AppServices) {
   if (
     target.kind === "settings" &&
     target.section &&
-    !["profile", "plugins", "appearance"].includes(target.section)
+    !["profile", "plugins", "appearance", "language"].includes(target.section)
   )
     failure = "unavailable";
   const owner = useMemo(
diff --git a/src/app/shell/AppShell.tsx b/src/app/shell/AppShell.tsx
index 5091fced..ac661811 100644
--- a/src/app/shell/AppShell.tsx
+++ b/src/app/shell/AppShell.tsx
@@ -8,6 +8,8 @@ import { ProfileButton } from "./ProfileButton";
 import { PageSearch } from "./PageSearch";
 import { orderPages, pagePresentation } from "./presentation";
 import { PanelFrame } from "../../features/panels/PanelFrame";
+import { useTranslation } from "react-i18next";
+import { localizedPageLabel } from "../../features/localization/service";
 
 const macDesktop = isTauri() && /Mac/i.test(navigator.platform);
 
@@ -36,6 +38,7 @@ export function AppShell({
   companion?: ReactNode;
   children: ReactNode;
 }) {
+  const { t } = useTranslation();
   return (
     <div
       data-shell-tone={tone}
@@ -51,7 +54,7 @@ export function AppShell({
         }}
         className="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:rounded-lg focus:bg-surface focus:p-3"
       >
-        Skip to content
+        {t("shell.skipToContent")}
       </a>
       <header
         data-tauri-drag-region
@@ -64,7 +67,7 @@ export function AppShell({
             onSelect={onCommunitySelect}
           />
         </div>
-        <nav aria-label="Pages" className="shell-pages">
+        <nav aria-label={t("shell.pages")} className="shell-pages">
           <button
             type="button"
             className="shell-tab"
@@ -72,7 +75,7 @@ export function AppShell({
             onClick={() => onSelect("home")}
           >
             <House aria-hidden="true" size={15} strokeWidth={1.7} />
-            Home
+            {t("shell.home")}
           </button>
           {orderPages(pages).map((page) => {
             const { label, icon: Icon } = pagePresentation(page);
@@ -85,7 +88,7 @@ export function AppShell({
                 onClick={() => onSelect(page.key)}
               >
                 <Icon aria-hidden="true" size={15} strokeWidth={1.7} />
-                {label}
+                {localizedPageLabel(page.key, label, t)}
               </button>
             );
           })}
diff --git a/src/app/shell/Home.tsx b/src/app/shell/Home.tsx
index 676320a0..f85da5c4 100644
--- a/src/app/shell/Home.tsx
+++ b/src/app/shell/Home.tsx
@@ -1,6 +1,8 @@
 import { ArrowUpRight, Settings2 } from "lucide-react";
 import type { RegisteredPage } from "../../features/pages/service";
 import { orderPages, pagePresentation } from "./presentation";
+import { useTranslation } from "react-i18next";
+import { localizedPageLabel } from "../../features/localization/service";
 
 export function Home({
   pages,
@@ -9,6 +11,7 @@ export function Home({
   pages: readonly RegisteredPage[];
   onSelect: (key: string) => void;
 }) {
+  const { t } = useTranslation();
   return (
     <section className="mx-auto max-w-2xl pt-8 sm:pt-16">
       <img
@@ -16,9 +19,9 @@ export function Home({
         alt="Buzz"
         className="mb-6 size-16 rounded-2xl"
       />
-      <p className="mb-2 text-sm text-muted">A little space for everything.</p>
+      <p className="mb-2 text-sm text-muted">{t("home.tagline")}</p>
       <h1 className="mb-8 text-4xl font-medium tracking-tight sm:text-5xl">
-        Make yourself at home.
+        {t("home.title")}
       </h1>
       <div className="overflow-hidden rounded-3xl border border-shell-edge/70 bg-surface/95 shadow-surface">
         {orderPages(pages).map((page) => {
@@ -33,7 +36,9 @@ export function Home({
               <span className="flex size-11 items-center justify-center rounded-2xl bg-shell">
                 <Icon size={21} aria-hidden="true" />
               </span>
-              <span className="flex-1 text-base font-medium">{label}</span>
+              <span className="flex-1 text-base font-medium">
+                {localizedPageLabel(page.key, label, t)}
+              </span>
               <ArrowUpRight
                 size={18}
                 className="text-muted"
@@ -51,8 +56,10 @@ export function Home({
             <Settings2 size={21} aria-hidden="true" />
           </span>
           <span className="flex-1">
-            <span className="block text-base font-medium">Make it yours</span>
-            <span className="text-sm text-muted">Settings</span>
+            <span className="block text-base font-medium">
+              {t("home.customize")}
+            </span>
+            <span className="text-sm text-muted">{t("shell.settings")}</span>
           </span>
           <ArrowUpRight size={18} className="text-muted" aria-hidden="true" />
         </button>
diff --git a/src/app/shell/PageSearch.tsx b/src/app/shell/PageSearch.tsx
index 06fc517b..a42cd360 100644
--- a/src/app/shell/PageSearch.tsx
+++ b/src/app/shell/PageSearch.tsx
@@ -6,6 +6,8 @@ import {
   pagePresentation,
   shellPresentation,
 } from "./presentation";
+import { useTranslation } from "react-i18next";
+import { localizedPageLabel } from "../../features/localization/service";
 
 export function PageSearch({
   pages,
@@ -14,15 +16,21 @@ export function PageSearch({
   pages: readonly RegisteredPage[];
   onSelect: (key: string) => void;
 }) {
+  const { t } = useTranslation();
   const dialog = useRef<HTMLDialogElement>(null);
   const [query, setQuery] = useState("");
   const destinations = [
-    { key: "home", ...shellPresentation.home },
+    { key: "home", ...shellPresentation.home, label: t("shell.home") },
     ...orderPages(pages).map((page) => ({
       key: page.key,
       ...pagePresentation(page),
+      label: localizedPageLabel(page.key, pagePresentation(page).label, t),
     })),
-    { key: "settings", ...shellPresentation.settings },
+    {
+      key: "settings",
+      ...shellPresentation.settings,
+      label: t("shell.settings"),
+    },
   ].filter((page) =>
     page.label.toLowerCase().includes(query.trim().toLowerCase()),
   );
@@ -31,8 +39,8 @@ export function PageSearch({
       <button
         type="button"
         className="shell-icon"
-        aria-label="Find a page"
-        title="Find a page"
+        aria-label={t("shell.findPage")}
+        title={t("shell.findPage")}
         onClick={() => {
           setQuery("");
           dialog.current?.showModal();
@@ -42,21 +50,21 @@ export function PageSearch({
       </button>
       <dialog
         ref={dialog}
-        aria-label="Find a page"
+        aria-label={t("shell.findPage")}
         className="m-auto w-[calc(100%-2rem)] max-w-md rounded-3xl border border-line bg-surface p-4 text-ink shadow-surface backdrop:bg-overlay"
       >
         <div className="mb-3 flex items-center gap-3 border-b border-line pb-3">
           <Search size={18} aria-hidden="true" />
           <input
-            aria-label="Find a page"
-            placeholder="Find a page…"
+            aria-label={t("shell.findPage")}
+            placeholder={t("shell.findPagePlaceholder")}
             value={query}
             onChange={(event) => setQuery(event.target.value)}
             className="min-w-0 flex-1 rounded bg-transparent py-2 text-sm"
           />
           <button
             type="button"
-            aria-label="Close search"
+            aria-label={t("shell.closeSearch")}
             className="shell-icon"
             onClick={() => dialog.current?.close()}
           >
@@ -80,7 +88,7 @@ export function PageSearch({
           ))}
           {!destinations.length && (
             <p role="status" className="px-3 text-sm text-muted">
-              No matching pages.
+              {t("shell.noMatchingPages")}
             </p>
           )}
         </div>
diff --git a/src/app/shell/ProfileButton.tsx b/src/app/shell/ProfileButton.tsx
index 2b3ea634..0db499ab 100644
--- a/src/app/shell/ProfileButton.tsx
+++ b/src/app/shell/ProfileButton.tsx
@@ -7,6 +7,7 @@ import {
 } from "react";
 import { Settings, UserRound } from "lucide-react";
 import type { Communities } from "../../features/communities/service";
+import { useTranslation } from "react-i18next";
 
 export function ProfileButton({
   communities,
@@ -17,6 +18,7 @@ export function ProfileButton({
   settingsSelected: boolean;
   onSettings(): void;
 }) {
+  const { t } = useTranslation();
   const { profile } = useSyncExternalStore(
     communities.subscribe,
     communities.snapshot,
@@ -54,10 +56,10 @@ export function ProfileButton({
           event.currentTarget.focus();
           setOpen((value) => !value);
         }}
-        aria-label="Your profile"
+        aria-label={t("shell.yourProfile")}
         aria-expanded={open}
         aria-controls={id}
-        title={profile.name || "Your profile"}
+        title={profile.name || t("shell.yourProfile")}
         className="flex size-9 shrink-0 items-center justify-center overflow-hidden rounded-full border-0 bg-surface/65 p-0 text-ink"
       >
         {/* Keep mouse-origin Tab traversal rooted at the button in WebKit. */}
@@ -80,12 +82,12 @@ export function ProfileButton({
       </button>
       <nav
         id={id}
-        aria-label="Your account"
+        aria-label={t("shell.yourAccount")}
         hidden={!open}
         className="absolute top-full right-0 z-50 mt-2 w-56 max-w-[calc(100vw-2rem)] rounded-2xl border border-line bg-surface p-2 shadow-surface"
       >
         <p className="m-0 truncate px-3 py-2 text-sm font-medium">
-          {profile.name || "Your account"}
+          {profile.name || t("shell.yourAccount")}
         </p>
         <button
           type="button"
@@ -98,7 +100,7 @@ export function ProfileButton({
           }}
         >
           <Settings aria-hidden="true" size={17} />
-          Settings
+          {t("shell.settings")}
         </button>
       </nav>
     </div>
diff --git a/src/features/localization/service.test.ts b/src/features/localization/service.test.ts
new file mode 100644
index 00000000..6962fd0f
--- /dev/null
+++ b/src/features/localization/service.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeLocale,
+  resolveInitialLocale,
+  translationResources,
+} from "./service";
+
+describe("application locale resolution", () => {
+  it("normalizes supported browser and persisted locale forms", () => {
+    expect(normalizeLocale("pt_BR")).toBe("pt-BR");
+    expect(normalizeLocale("pt-BR")).toBe("pt-BR");
+    expect(normalizeLocale("en-GB")).toBe("en-US");
+    expect(normalizeLocale("pt-PT")).toBeUndefined();
+    expect(normalizeLocale("es-BR")).toBeUndefined();
+  });
+
+  it("prefers a supported saved locale over browser preferences", () => {
+    expect(resolveInitialLocale("pt-BR", ["en-US"])).toBe("pt-BR");
+    expect(resolveInitialLocale("invalid", ["pt-BR", "en-US"])).toBe("pt-BR");
+  });
+
+  it("falls back to English when no supported preference exists", () => {
+    expect(resolveInitialLocale(undefined, ["es-ES", "fr-FR"])).toBe("en-US");
+  });
+
+  it("keeps every supported catalogue structurally complete", () => {
+    const englishKeys = Object.keys(
+      translationResources["en-US"].translation,
+    ).sort();
+    const portugueseKeys = Object.keys(
+      translationResources["pt-BR"].translation,
+    ).sort();
+    expect(portugueseKeys).toEqual(englishKeys);
+  });
+});
diff --git a/src/features/localization/service.ts b/src/features/localization/service.ts
new file mode 100644
index 00000000..e4d61ae2
--- /dev/null
+++ b/src/features/localization/service.ts
@@ -0,0 +1,153 @@
+import i18next, { type TFunction } from "i18next";
+import { initReactI18next } from "react-i18next";
+
+export const appLocales = ["en-US", "pt-BR"] as const;
+export type AppLocale = (typeof appLocales)[number];
+
+const storageKey = "buzz.language";
+
+export const translationResources = {
+  "en-US": {
+    translation: {
+      "shell.skipToContent": "Skip to content",
+      "shell.pages": "Pages",
+      "shell.home": "Home",
+      "shell.messages": "Messages",
+      "shell.projects": "Projects",
+      "shell.findPage": "Find a page",
+      "shell.findPagePlaceholder": "Find a page…",
+      "shell.closeSearch": "Close search",
+      "shell.noMatchingPages": "No matching pages.",
+      "shell.yourProfile": "Your profile",
+      "shell.yourAccount": "Your account",
+      "shell.settings": "Settings",
+      "home.tagline": "A little space for everything.",
+      "home.title": "Make yourself at home.",
+      "home.customize": "Make it yours",
+      "settings.title": "Settings",
+      "settings.sections": "Settings sections",
+      "settings.profile": "Profile",
+      "settings.plugins": "Plugins",
+      "settings.appearance": "Appearance",
+      "settings.language": "Language",
+      "language.title": "Language",
+      "language.label": "Application language",
+      "language.description":
+        "Choose the language used by Buzz on this device. Your choice is saved automatically.",
+      "language.english": "English (United States)",
+      "language.portugueseBrazil": "Português (Brasil)",
+    },
+  },
+  "pt-BR": {
+    translation: {
+      "shell.skipToContent": "Pular para o conteúdo",
+      "shell.pages": "Páginas",
+      "shell.home": "Início",
+      "shell.messages": "Mensagens",
+      "shell.projects": "Projetos",
+      "shell.findPage": "Buscar uma página",
+      "shell.findPagePlaceholder": "Buscar uma página…",
+      "shell.closeSearch": "Fechar busca",
+      "shell.noMatchingPages": "Nenhuma página encontrada.",
+      "shell.yourProfile": "Seu perfil",
+      "shell.yourAccount": "Sua conta",
+      "shell.settings": "Configurações",
+      "home.tagline": "Um espaço para tudo.",
+      "home.title": "Sinta-se em casa.",
+      "home.customize": "Deixe do seu jeito",
+      "settings.title": "Configurações",
+      "settings.sections": "Seções das configurações",
+      "settings.profile": "Perfil",
+      "settings.plugins": "Plugins",
+      "settings.appearance": "Aparência",
+      "settings.language": "Idioma",
+      "language.title": "Idioma",
+      "language.label": "Idioma do aplicativo",
+      "language.description":
+        "Escolha o idioma usado pelo Buzz neste dispositivo. Sua escolha é salva automaticamente.",
+      "language.english": "English (United States)",
+      "language.portugueseBrazil": "Português (Brasil)",
+    },
+  },
+} as const;
+
+export function normalizeLocale(value: unknown): AppLocale | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replaceAll("_", "-").toLowerCase();
+  if (normalized === "pt" || normalized === "pt-br") return "pt-BR";
+  if (normalized === "en" || normalized.startsWith("en-")) return "en-US";
+  return undefined;
+}
+
+export function resolveInitialLocale(
+  saved: unknown,
+  preferred: readonly string[],
+): AppLocale {
+  const stored = normalizeLocale(saved);
+  if (stored) return stored;
+  for (const candidate of preferred) {
+    const locale = normalizeLocale(candidate);
+    if (locale) return locale;
+  }
+  return "en-US";
+}
+
+function readStoredLocale() {
+  try {
+    return globalThis.localStorage?.getItem(storageKey);
+  } catch {
+    return undefined;
+  }
+}
+
+function preferredLocales() {
+  if (typeof navigator === "undefined") return [];
+  return navigator.languages?.length
+    ? navigator.languages
+    : navigator.language
+      ? [navigator.language]
+      : [];
+}
+
+function updateDocumentLanguage(locale: string) {
+  if (typeof document !== "undefined") document.documentElement.lang = locale;
+}
+
+export const appI18n = i18next.createInstance();
+void appI18n.use(initReactI18next).init({
+  resources: translationResources,
+  lng: resolveInitialLocale(readStoredLocale(), preferredLocales()),
+  fallbackLng: "en-US",
+  supportedLngs: appLocales,
+  load: "currentOnly",
+  keySeparator: false,
+  interpolation: { escapeValue: false },
+  react: { useSuspense: false },
+});
+updateDocumentLanguage(appI18n.resolvedLanguage ?? appI18n.language);
+appI18n.on("languageChanged", updateDocumentLanguage);
+
+export function currentLocale(): AppLocale {
+  return (
+    normalizeLocale(appI18n.resolvedLanguage ?? appI18n.language) ?? "en-US"
+  );
+}
+
+export async function setAppLocale(locale: AppLocale) {
+  try {
+    globalThis.localStorage?.setItem(storageKey, locale);
+  } catch {
+    // Language changes still apply to this session when storage is unavailable.
+  }
+  await appI18n.changeLanguage(locale);
+}
+
+export function localizedPageLabel(
+  key: string,
+  fallback: string,
+  t: TFunction,
+) {
+  if (key === "buzz.channels/channels") return t("shell.messages");
+  if (key === "buzz.projects/projects") return t("shell.projects");
+  return fallback;
+}
diff --git a/tests/browser/settings.spec.mjs b/tests/browser/settings.spec.mjs
index f94396f5..782ed29a 100644
--- a/tests/browser/settings.spec.mjs
+++ b/tests/browser/settings.spec.mjs
@@ -126,12 +126,46 @@ test("avatar Settings access dismisses cleanly and exposes Profile and Plugins",
       sections.getByRole("button", { name: "Appearance", exact: true }),
     ).toBeFocused();
     await tab();
+    await expect(
+      sections.getByRole("button", { name: "Language", exact: true }),
+    ).toBeFocused();
+    await tab();
     await expect(
       page.getByRole("textbox", { name: "Display name", exact: true }),
     ).toBeFocused();
   }
 });
 
+test("language selection applies Brazilian Portuguese and persists after reload", async ({
+  page,
+  app,
+}) => {
+  await page.goto(app.origin);
+  await button(page, "Your profile").click();
+  await button(page, "Settings").click();
+  await button(page, "Language").click();
+
+  const language = page.getByRole("combobox", {
+    name: "Application language",
+  });
+  await language.selectOption("pt-BR");
+
+  await expect(
+    page.getByRole("heading", { name: "Configurações", exact: true }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("navigation", { name: "Seções das configurações" }),
+  ).toBeVisible();
+  await expect(button(page, "Início")).toBeVisible();
+  await expect(button(page, "Mensagens")).toBeVisible();
+  await expect(page.locator("html")).toHaveAttribute("lang", "pt-BR");
+
+  await page.reload();
+  await expect(button(page, "Início")).toBeVisible();
+  await expect(button(page, "Mensagens")).toBeVisible();
+  await expect(page.locator("html")).toHaveAttribute("lang", "pt-BR");
+});
+
 test("Settings edits the local profile inline without publishing to a community", async ({
   page,
   app,