---
name: t
kind: function
lang: py
domain: core
version: "1.0.0"
purity: impure
signature: "def t(key: str, locale: str | None = None, **kwargs) -> str"
description: "Traduce una clave con dot-path notation al idioma activo. Prioridad: parametro locale > thread-local > default. Soporta interpolacion {variable}. Fallback al locale default si la clave no existe; si tampoco existe, retorna la key."
tags: [i18n, translation, locale, dot-path, interpolation]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [threading]
params:
  - name: key
    desc: "Clave de traducción con dot-path notation (ej: 'report.done')"
  - name: locale
    desc: "Locale a usar (default: usa locale thread-local)"
  - name: kwargs
    desc: "Variables para interpolación en el template"
output: "String traducido e interpolado, o la key si no se encuentra traducción"
tested: true
tests: ["key existente retorna traduccion", "key inexistente retorna la key", "interpolacion de variables", "dot-path profundo", "fallback a locale default"]
test_file_path: "python/functions/core/t_test.py"
file_path: "python/functions/core/t.py"
---

## Ejemplo

```python
from t import t, _set_translations

translations = {
    "en": {
        "report": {
            "sectionStart": "Generating section: {title}",
            "done": "Done"
        }
    },
    "es": {
        "report": {
            "done": "Listo"
        }
    }
}
_set_translations(translations, default_locale="en")

t("report.sectionStart", locale="en", title="Introduction")
# → "Generating section: Introduction"

t("report.done", locale="es")
# → "Listo"

t("report.sectionStart", locale="es", title="Intro")
# → "Generating section: Intro"  (fallback a en)

t("nonexistent.key", locale="en")
# → "nonexistent.key"
```

## Notas

Lee estado global (modulo-level `_translations` y `_locale_local` thread-local), por eso es impura. Configurar con `_set_translations()` al inicio de la aplicacion y `_set_locale()` por thread/request. La interpolacion usa `str.format(**kwargs)` — si hay un placeholder faltante, retorna el string sin interpolar para no romper el flujo. Inspirada conceptualmente en el modulo `locale.py` de MiroFish (AGPL-3.0); reimplementada desde cero.
