# General Translation Python SDKs: declare_var
URL: https://generaltranslation.com/zh/docs/python/reference/functions/declare-var.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation Python 中 declare_var 的 API 参考。将动态值标记为不可翻译的变量。

不可翻译的变量是指在不同语言中保持不变的动态值。可对仅在运行时才能确定的值使用 `declare_var`，例如嵌入在 [`t`](/docs/python/reference/functions/t) 调用中的用户名、电子邮件地址和数量。

## 概览 [#overview]

调用 `declare_var` 时，传入一个值，以及可选的仅限关键字参数 `name`。它会返回一个 ICU `{_gt_, select, ...}` 结构，用于将该值嵌入为 General Translation 的变量标记。

```python
from gt_flask import declare_var  # 或：from gt_fastapi import declare_var，或：from gt_i18n import declare_var

t(f"Signed in as {declare_var(email, name='email')}")
```

签名：

```python
declare_var(
    variable: str | int | float | bool | None,
    *,
    name: str | None = None,
) -> str
```

由 `gt_i18n` 和各框架包从 `generaltranslation.static` 重新导出。

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

* **值格式化。** `None` 会变成空字符串，`bool` 会变成 `"true"`/`"false"`，其他值会被转换为字符串；结果会经过清理。
* **标记构造。** 它会返回 `{_gt_, select, other {value}}`；如果提供了 `name`，还会额外带上 `_gt_var_name {name}` 子句。
* **运行时与构建时。** 适用于运行时值；如果某个值在构建时只有有限种可能结果，请使用 [`derive`](/docs/python/reference/functions/derive)。使用 [`decode_vars`](/docs/python/reference/functions/decode-vars) 可恢复嵌入的值。

## 参数 [#parameters]

| 参数                      | 描述                   | Type                                  | 可选 | 默认值    |
| ----------------------- | -------------------- | ------------------------------------- | -- | ------ |
| [`variable`](#variable) | 要作为不可翻译变量嵌入的值。       | `str \| int \| float \| bool \| None` | 否  | —      |
| [`name`](#name)         | 仅限关键字的人类可读变量名。 | `str`                                 | 是  | `None` |

### `variable` [#variable]

**类型** `str | int | float | bool | None` · **必填**

要嵌入的值。`None` 会渲染为空字符串；布尔值会以小写形式渲染。

### `name` [#name]

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

变量的一个仅限关键字、人类可读的标签；提供时会以 `_gt_var_name` 子句的形式添加。

## 返回值 [#returns]

**类型** `str`

一个 ICU `{_gt_, select, ...}` 结构，用于将该值包装为变量标记。

## 示例 [#example]

```python
from gt_flask import t, declare_var

# 在已翻译的 f-string 中保留运行时值
message = t(f"{declare_var(name, name='name')} goes home")
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.