# General Translation Python SDKs: interpolate_message
URL: https://generaltranslation.com/zh/docs/python/reference/functions/interpolate-message.mdx
---

title: interpolate_message
description: 在 General Translation Python 中将变量插值到 ICU MessageFormat 字符串中。interpolate_message 的 API 参考。

---

将变量插值到 ICU MessageFormat 字符串中。这是 [`t`](/docs/python/reference/functions/t) 和 [`t_fallback`](/docs/python/reference/functions/t-fallback) 使用的底层格式化器；它不会执行翻译查找。

## 概览 [#overview]

调用 `interpolate_message` 时，传入消息、选项 `dict` 以及可选的区域设置。与 `t` 和 `t_fallback` 不同，变量需要以位置参数 `dict` 的形式传入，而不是作为关键字参数传入。

```python
from gt_i18n import interpolate_message

interpolate_message("Hello, {name}!", {"name": "Alice"})
```

签名：

```python
interpolate_message(
    message: str,
    options: dict[str, object],
    locale: str | None = None,
) -> str
```

从 `gt_i18n` 导入 `interpolate_message`。框架包不会再次导出它。

## 工作原理 [#how-it-works]

* **过滤变量。** 从 `options` 中移除 GT 的保留键，仅保留用户变量。
* **已声明变量。** 它会从 `__fallback` (源) 消息中提取已声明的 `_gt_` 变量；如果存在这类变量，则将消息中带索引的 select 压缩为简单引用，以便译文能够重新调整它们的顺序。
* **格式化。** 它会使用合并后的变量，通过 ICU MessageFormat 对消息进行格式化，然后在设置了 `_max_chars` 时应用截断。
* **错误处理。** 如果格式化出错，它会使用 `__fallback` 源消息重试 (同时清除 `__fallback` 以避免循环) ；如果没有后备内容，则返回原始消息，并在设置了 `_max_chars` 时应用截断。

## 参数 [#parameters]

| 参数                    | 描述                            | Type                | Optional | Default |
| --------------------- | ----------------------------- | ------------------- | -------- | ------- |
| [`message`](#message) | 要进行插值的 ICU MessageFormat 字符串。 | `str`               | 否        | —       |
| [`options`](#options) | 以 dict 形式传入的变量和 GT 选项。        | `dict[str, object]` | 否        | —       |
| [`locale`](#locale)   | 用于 ICU 格式化的区域设置。              | `str \| None`       | 是        | `None`  |

### `message` [#message]

**类型** `str` · **必填**

要进行插值的 ICU MessageFormat 字符串。

### `options` [#options]

**类型** `dict[str, object]` · **必填**

用户变量，以及可选的 GT 键：`_max_chars` 用于设置截断上限，`__fallback` (源消息) 用于解析已声明的 `_gt_` 变量，并在出错时重试。

### `locale` [#locale]

**类型** `str | None` · **可选** · **默认值** `None`

传递给 ICU 格式化功能的区域设置 (用于数字、日期和复数规则) 。

## 返回值 [#returns]

**类型** `str`

插值后的字符串；如果格式化失败，则返回原始消息或后备内容。

## 示例 [#example]

```python
from gt_i18n import interpolate_message

interpolate_message("{greeting}, {name}!", {"greeting": "Hi", "name": "Bob"})
# → "Hi, Bob!"

# 已翻译的消息，通过索引引用源文本中声明的变量
interpolate_message("Bienvenido de nuevo, {_gt_1}!", {"__fallback": source})
```