# General Translation Python SDKs: t
URL: https://generaltranslation.com/fr/docs/python/reference/functions/t.mdx
---

title: t
description: Traduire et interpoler une chaîne ICU MessageFormat avec General Translation en Python. Référence de l’API pour `t`.

---

Traduit et interpole une chaîne ICU MessageFormat selon le paramètre régional actif de la requête. `t` est la principale fonction de traduction destinée aux utilisateurs.

## Vue d’ensemble [#overview]

Appelez `t` avec une chaîne source et toute variable d’interpolation sous forme d’arguments par mot-clé. Elle renvoie la chaîne traduite et interpolée pour le paramètre régional actuel et, si aucune traduction n’est trouvée, utilise la source interpolée.

```python
from gt_flask import t  # ou : from gt_fastapi import t, ou : from gt_i18n import t

message = t("Hello, {name}!", name="World")
```

Signature :

```python
t(message: str, **kwargs: object) -> str
```

*Remarque : `t` utilise le gestionnaire actif, donc [`initialize_gt`](/docs/python/reference/functions/initialize-gt) (ou [`set_i18n_manager`](/docs/python/reference/functions/set-i18n-manager)) doit être exécuté au préalable. Sinon, une `RuntimeError` est levée.*

## Fonctionnement [#how-it-works]

* **Vérification du paramètre régional.** Le système lit le paramètre régional actuel depuis le gestionnaire. Si ce paramètre régional ne nécessite pas de traduction (par exemple, s’il correspond au paramètre régional par défaut), il ignore la recherche et interpole uniquement la source.
* **Recherche par hachage.** Sinon, il calcule le hachage du message (avec `_context`, `_id` et `_max_chars`) et récupère dans le cache en mémoire la traduction mise en cache pour le paramètre régional. Le cache est synchrone, donc une traduction doit déjà être chargée — voir le [préchargement](/docs/python/guides/configuring#preload).
* **Interpolation.** La traduction trouvée est interpolée avec ICU MessageFormat, en utilisant vos variables et la source comme `__fallback` pour résoudre les variables `_gt_` déclarées.
* **Contenu de secours.** Si aucune traduction n’est trouvée, la chaîne source est interpolée puis renvoyée.

## Paramètres [#parameters]

| Paramètre             | Description                                           | Type             | Facultatif | Par défaut |
| --------------------- | ----------------------------------------------------- | ---------------- | ---------- | ---------- |
| [`message`](#message) | La chaîne source au format ICU MessageFormat.         | `str`            | Non        | —          |
| [`kwargs`](#kwargs)   | Variables d’interpolation et options réservées de GT. | arguments nommés | Oui        | —          |

### `message` [#message]

**Type** `str` · **Obligatoire**

La chaîne source au format ICU MessageFormat à traduire et à interpoler.

### `kwargs` [#kwargs]

**Type** arguments par mot-clé · **Facultatif**

Variables d’interpolation correspondant aux placeholders ICU, ainsi que les options GT réservées ci-dessous, qui sont exclues de l’interpolation et intégrées au hachage du message :

* `_context` (`str`) — contexte supplémentaire pour désambiguïser des traductions ayant le même texte source.
* `_id` (`str`) — identifiant personnalisé pour l’entrée de traduction.
* `_max_chars` (`int`) — longueur maximale en caractères appliquée à la sortie.

*Une variable utilisateur dont le nom commence par un seul trait de soulignement (par exemple, `_name`) est toujours traitée comme une variable d’interpolation ; seules les trois clés ci-dessus sont réservées.*

## Valeur de retour [#returns]

**Type** `str`

La chaîne traduite et interpolée, ou la chaîne source interpolée lorsqu’aucune traduction n’est disponible.

## Exemples [#examples]

```python
# Traduction simple
t("Hello, world!")
```

```python
# Avec des variables
t("Hello, {name}!", name="Alice")
```

```python
# Avec contexte pour lever l'ambiguïté d'un texte source identique
t("Bank", _context="financial institution")
t("Bank", _context="river bank")
```

```python
# Avec les f-strings et declare_var — encapsulez les valeurs dynamiques pour qu'elles soient préservées
from gt_flask import t, declare_var

# Avant i18n :
message = f"{name} goes home"

# Après i18n — encapsulez avec t() et declare_var() :
message = t(f"{declare_var(name, name='name')} goes home")
```

```python
# Avec une limite de caractères
t("This is a very long message that might need truncation", _max_chars=20)
```