docs: document i18n architecture and localized surfaces

README.md

@@ -45,6 +45,27 @@ Stock Manager permite gestionar:
 | Formato/lint | Biome |
 | Deploy | Docker / Docker Compose |
 
+## Internacionalización (i18n)
+
+La aplicación soporta inglés (`en`) y español (`es`) en todas las superficies de usuario. La selección de idioma se persiste mediante una cookie `stock-manager-locale` validada en servidor y se aplica con un cambio de idioma por página sin rutas prefijadas.
+
+Superficies localizadas:
+
+- **Login** y navbar compartida con selector de idioma compacto.
+- **Shell común**: sidebar, navegación, search, paginación, botón submit, página de acceso denegado.
+- **Inventario**: categorías, ítems, activos, destinatarios, asignaciones, movimientos.
+- **Admin**: gestión de usuarios, roles y estado.
+
+La arquitectura i18n sigue un patrón consistente:
+
+- **Diccionarios tipados** en `src/i18n/dictionaries/en.ts` y `es.ts` con paridad de claves obligatoria.
+- **Resolución server-side**: las páginas obtienen `getI18n()` y pasan props acotadas a componentes cliente.
+- **Schemas localizados**: builders (`buildCreateXSchema(copy)`) que aceptan copia de diccionario e inyectan mensajes de validación localizados.
+- **Actions localizadas**: resuelven locale en servidor, construyen schemas con copia localizada y mapean errores de use-case mediante message mappers.
+- **Datos de usuario vs UI**: nombres, emails, seriales y valores de enumeraciones canónicas nunca se traducen; solo se localizan las etiquetas de presentación.
+
+La importación CSV queda fuera del alcance actual de i18n por su rediseño previsto.
+
 ## Configuración de entorno
 
 Copiá el ejemplo y completá los valores reales: