diff --git a/CHANGELOG.md b/CHANGELOG.md
index eef358c..9adee7d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Locale switcher — a `<select>` dropdown in the header lets users switch languages at runtime; locale is stored in the session and applied via `I18n.with_locale`; automatically hidden when only one locale is configured
 - `config.available_locales` — controls which locales appear in the switcher (default: `[:en, :es]`)
 
+### Changed
+
+- README — added a table of contents, back-to-top navigation links to each major section, and a dedicated i18n section documenting locale switching, `config.available_locales`, and how to add a custom locale
+
 ## [1.5.0] - 2026-05-29
 
 ### Changed
diff --git a/README.md b/README.md
index aa449f9..0c1748b 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,39 @@
 
 A production-ready operations dashboard for the full Rails Solid Stack. Mount one engine to get deep visibility into **Solid Queue** (job browser, failed job retry, queue controls, recurring tasks, performance stats), **Solid Cache** (entry browser, size distribution, write timeline), and **Solid Cable** (channel browser, message list, purge controls) — with dark mode, i18n locale switching, CSV export, alert webhooks, and a JSON metrics endpoint, all with no asset pipeline dependency.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Screenshots](#screenshots)
+- [Metrics endpoint](#metrics-endpoint)
+- [General configuration](#general-configuration)
+  - [Authentication](#authentication)
+  - [Linking to the dashboard](#linking-to-the-dashboard)
+- [i18n](#i18n)
+  - [Adding a custom locale](#adding-a-custom-locale)
+- [Security](#security)
+  - [Authentication](#authentication-1)
+  - [Sensitive cache values](#sensitive-cache-values)
+  - [CSRF protection](#csrf-protection)
+  - [Rate limiting and network exposure](#rate-limiting-and-network-exposure)
+- [Solid Queue](#solid-queue)
+  - [Features](#features)
+  - [Configuration](#configuration)
+    - [Job Filtering](#job-filtering)
+- [Solid Cache](#solid-cache)
+  - [Features](#features-1)
+- [Solid Cable](#solid-cable)
+  - [Features](#features-2)
+- [Requirements](#requirements)
+- [Versioning](#versioning)
+  - [Public API](#public-api)
+  - [Not part of the public API](#not-part-of-the-public-api)
+  - [Deprecation policy](#deprecation-policy)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Installation
 
 Add the gem to your application's `Gemfile`:
@@ -30,12 +63,16 @@ rails generate solid_stack_web:install
 
 This creates `config/initializers/solid_stack_web.rb` with every configuration option commented inline, and injects `mount SolidStackWeb::Engine, at: "/solid_stack"` into `config/routes.rb`. The dashboard will then be available at `/solid_stack` (or whatever path you choose).
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Screenshots
 
 ![SolidStackWeb dashboard](docs/screenshots/demo.gif)
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Metrics endpoint
@@ -64,6 +101,8 @@ This creates `config/initializers/solid_stack_web.rb` with every configuration o
 
 `slow_jobs` is only present when `slow_job_threshold` is configured. The endpoint is protected by the same authentication as the rest of the dashboard.
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## General configuration
@@ -99,6 +138,40 @@ The `authenticate` block is evaluated in the context of each request's controlle
 link_to "Queue Dashboard", SolidStackWeb.mount_path
 ```
 
+[↑ Back to top](#table-of-contents)
+
+---
+
+## i18n
+
+All dashboard UI strings — page titles, table headers, button labels, empty states, flash messages, and sparkline tooltips — are backed by locale YAML files. The engine ships with **English (`en`)** and **Spanish (`es`)** built in.
+
+A language selector appears in the dashboard header and lets users switch locales at runtime. The selected locale is stored in the session and applied via `I18n.with_locale`, so it persists across requests without touching the host application's locale. The `?locale=` query param takes precedence over the session value, making it easy to deep-link to a specific language.
+
+The switcher is automatically hidden when `config.available_locales` contains only one entry.
+
+```ruby
+SolidStackWeb.configure do |config|
+  # Locales shown in the language switcher (default: [:en, :es]).
+  # Set to [:en] to hide the switcher entirely.
+  config.available_locales = [:en, :es]
+end
+```
+
+### Adding a custom locale
+
+1. Create a locale file in your host application under `config/locales/`, e.g. `config/locales/solid_stack_web.fr.yml`.
+2. Nest all keys under `fr > solid_stack_web:` — use `config/locales/en.yml` in the gem as a reference for the full key list.
+3. Add the locale symbol to `config.available_locales`:
+
+```ruby
+config.available_locales = [:en, :es, :fr]
+```
+
+Rails will pick up the file automatically via its standard `config.i18n.load_path`; no additional configuration is needed.
+
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Security
@@ -137,6 +210,8 @@ The dashboard is designed to be mounted behind your application's existing authe
 - Restricting access by IP at the reverse-proxy level
 - Applying [Rack::Attack](https://github.com/rack/rack-attack) rules to the mount path
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Solid Queue
@@ -215,6 +290,8 @@ The jobs list supports four independent filters, all driven by query params:
 
 Filters are preserved when switching between status tabs (Ready / Scheduled / Running / Blocked) and when discarding a job. They can be combined freely.
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Solid Cache
@@ -231,6 +308,8 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
 - **Delete entry** — per-row delete button or detail-page button removes a single cache entry
 - **Flush All** — header button deletes every cache entry with a confirmation prompt
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Solid Cable
@@ -243,6 +322,8 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
 - **Per-channel message list** — `GET /cable/channels/:channel_hash` shows a paginated, reverse-chronological list of that channel's `SolidCable::Message` records; each row shows the message ID, a truncated payload preview (120 chars) with the full payload on hover, and a relative sent time with the exact timestamp on hover; supports `?q=` filtering by payload substring; **Purge Channel** button deletes all messages for the channel
 - **Message purge** — "Purge Old" form on the channel browser deletes all messages older than 1, 7, or 30 days; confirmation prompt before any destructive action
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Requirements
@@ -255,6 +336,10 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru
 - [turbo-rails](https://github.com/hotwired/turbo-rails) >= 2.0
 - [importmap-rails](https://github.com/rails/importmap-rails) >= 1.2
 
+[↑ Back to top](#table-of-contents)
+
+---
+
 ## Versioning
 
 SolidStackWeb follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -283,6 +368,8 @@ The following are internal and may change in any release without notice:
 
 When a public API item is renamed or removed, the old interface is deprecated in a **minor** release — it continues to work but issues an `ActiveSupport::Deprecation` warning pointing to the replacement. The old interface is removed in the next **major** release. The [UPGRADING.md](UPGRADING.md) file documents every breaking change and the migration steps.
 
+[↑ Back to top](#table-of-contents)
+
 ---
 
 ## Contributing
@@ -294,6 +381,12 @@ When a public API item is renamed or removed, the old interface is deprecated in
 
 Bug reports and feature requests are welcome on [GitHub Issues](https://github.com/eclectic-coding/solid_stack_web/issues).
 
+[↑ Back to top](#table-of-contents)
+
+---
+
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
\ No newline at end of file
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[↑ Back to top](#table-of-contents)
\ No newline at end of file