error message with i18n support in FastAPI
## response example
```json
{
"errors": [
{
"loc": [
"body",
"string"
],
"msg": "確保此值最多有 10 個字符",
"type": "value_error.any_str.max_length",
"ctx": {
"limit_value": 10
}
},
{
"loc": [
"body",
"nested",
"body"
],
"msg": "確保此值最多有 2 個字符",
"type": "value_error.any_str.max_length",
"ctx": {
"limit_value": 2
}
},
{
"loc": [
"body",
"nested",
"inner",
"inner_body"
],
"msg": "確保此值最多包含 2 個項目",
"type": "value_error.list.max_items",
"ctx": {
"limit_value": 2
}
},
{
"loc": [
"body",
"nested",
"inner",
"cat"
],
"msg": "鑑別器 'color' 和值 'ccc' 不匹配（允許的值: 'black', 'white'）",
"type": "value_error.discriminated_union.invalid_discriminator",
"ctx": {
"discriminator_key": "color",
"discriminator_value": "ccc",
"allowed_values": "'black', 'white'"
}
}
]
}
```
## parameters
all parameters are optional
| param | description | default |
|-------------------|----------------------------------------------------------------------------------|-----------------------------|
| locale_path | the path of your locale files | locales |
| locale_list | support locales in your app in tuple | ('zh-TW', 'ja-JP', 'en-US') |
| bind_to_life_span | set to `True` if you want the translator instance be created when on app startup | False |
## Attention
- For FastAPI >=0.100.0 and pydantic v2, please use **^0.4.0**
- For FastAPI < 0.100.0 nad pydantic v1, please use **^0.3.0**
- built-in locales are **zh-TW, en-US, ja-JP**, you can change the locales by yourself
## How to run
- use `setup`
```py
from fastapi_validation_i18n import setup
from fastapi import FastAPI
app = FastAPI()
setup(app, locale_path=..., locale_list=...)
```
- use middleware and exception handler
```py
from fastapi import FastAPI
from fastapi_validation_i18n import I18nMiddleware, i18n_exception_handler
from fastapi.exceptions import RequestValidationError
app = FastAPI()
app.add_middleware(I18nMiddleware, locale_path='your-publish-path')
app.add_exception_handler(
RequestValidationError,
i18n_exception_handler
)
```
## Other
- publish locales to your app path
```bash
# default to "locale" in your project path
uv run publish-locale <your-path> [--locale]
```
- how to set locale
there are 3 ways to set locale
1. set `accept-language` header to your request
2. set an API with `locale` in path
3. set `locale` query parameter to your request
you can see the [example](https://github.com/whchi/fastapi-validation-i18n/tree/main/example) for more detail
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-validation-i18n",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fastapi, i18n, pydantic, validation",
"author": null,
"author_email": "whchi <whccchi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d8/9d/6211c8ff1c649ea6a8e22b362e61a8eb9545e1571eae21e07e995022fa13/fastapi_validation_i18n-0.4.3.tar.gz",
"platform": null,
"description": "\n\nerror message with i18n support in FastAPI\n\n## response example\n```json\n{\n \"errors\": [\n {\n \"loc\": [\n \"body\",\n \"string\"\n ],\n \"msg\": \"\u78ba\u4fdd\u6b64\u503c\u6700\u591a\u6709 10 \u500b\u5b57\u7b26\",\n \"type\": \"value_error.any_str.max_length\",\n \"ctx\": {\n \"limit_value\": 10\n }\n },\n {\n \"loc\": [\n \"body\",\n \"nested\",\n \"body\"\n ],\n \"msg\": \"\u78ba\u4fdd\u6b64\u503c\u6700\u591a\u6709 2 \u500b\u5b57\u7b26\",\n \"type\": \"value_error.any_str.max_length\",\n \"ctx\": {\n \"limit_value\": 2\n }\n },\n {\n \"loc\": [\n \"body\",\n \"nested\",\n \"inner\",\n \"inner_body\"\n ],\n \"msg\": \"\u78ba\u4fdd\u6b64\u503c\u6700\u591a\u5305\u542b 2 \u500b\u9805\u76ee\",\n \"type\": \"value_error.list.max_items\",\n \"ctx\": {\n \"limit_value\": 2\n }\n },\n {\n \"loc\": [\n \"body\",\n \"nested\",\n \"inner\",\n \"cat\"\n ],\n \"msg\": \"\u9451\u5225\u5668 'color' \u548c\u503c 'ccc' \u4e0d\u5339\u914d\uff08\u5141\u8a31\u7684\u503c: 'black', 'white'\uff09\",\n \"type\": \"value_error.discriminated_union.invalid_discriminator\",\n \"ctx\": {\n \"discriminator_key\": \"color\",\n \"discriminator_value\": \"ccc\",\n \"allowed_values\": \"'black', 'white'\"\n }\n }\n ]\n}\n```\n## parameters\nall parameters are optional\n\n| param | description | default |\n|-------------------|----------------------------------------------------------------------------------|-----------------------------|\n| locale_path | the path of your locale files | locales |\n| locale_list | support locales in your app in tuple | ('zh-TW', 'ja-JP', 'en-US') |\n| bind_to_life_span | set to `True` if you want the translator instance be created when on app startup | False |\n\n## Attention\n- For FastAPI >=0.100.0 and pydantic v2, please use **^0.4.0**\n- For FastAPI < 0.100.0 nad pydantic v1, please use **^0.3.0**\n- built-in locales are **zh-TW, en-US, ja-JP**, you can change the locales by yourself\n\n## How to run\n- use `setup`\n```py\nfrom fastapi_validation_i18n import setup\nfrom fastapi import FastAPI\napp = FastAPI()\nsetup(app, locale_path=..., locale_list=...)\n\n```\n- use middleware and exception handler\n```py\nfrom fastapi import FastAPI\nfrom fastapi_validation_i18n import I18nMiddleware, i18n_exception_handler\nfrom fastapi.exceptions import RequestValidationError\n\napp = FastAPI()\n\napp.add_middleware(I18nMiddleware, locale_path='your-publish-path')\n\napp.add_exception_handler(\n RequestValidationError,\n i18n_exception_handler\n)\n```\n## Other\n- publish locales to your app path\n```bash\n# default to \"locale\" in your project path\nuv run publish-locale <your-path> [--locale]\n```\n\n- how to set locale\n\nthere are 3 ways to set locale\n1. set `accept-language` header to your request\n2. set an API with `locale` in path\n3. set `locale` query parameter to your request\n\nyou can see the [example](https://github.com/whchi/fastapi-validation-i18n/tree/main/example) for more detail\n",
"bugtrack_url": null,
"license": null,
"summary": "FastAPI request validation with i18n error message",
"version": "0.4.3",
"project_urls": {
"Repository": "https://github.com/whchi/fastapi-validation-i18n"
},
"split_keywords": [
"fastapi",
" i18n",
" pydantic",
" validation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c8881c4f08692027f4279c75c36a46d0b6babbe4911ca5786b276ba78e1d129",
"md5": "87c8393bc1f3f30b02ab88254f30f420",
"sha256": "6d762165de5a96dd1a159a224f0a14a752a76cf6a3ac9d14f7d3c1f5f6301f12"
},
"downloads": -1,
"filename": "fastapi_validation_i18n-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87c8393bc1f3f30b02ab88254f30f420",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16774,
"upload_time": "2025-08-12T02:57:27",
"upload_time_iso_8601": "2025-08-12T02:57:27.076569Z",
"url": "https://files.pythonhosted.org/packages/4c/88/81c4f08692027f4279c75c36a46d0b6babbe4911ca5786b276ba78e1d129/fastapi_validation_i18n-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d89d6211c8ff1c649ea6a8e22b362e61a8eb9545e1571eae21e07e995022fa13",
"md5": "160555a0c82a19b9050996eeddc8f28c",
"sha256": "c1bfe69743e6ddfc8b932cdb0425f7edba53455c8727e9384645da93f4e8f97a"
},
"downloads": -1,
"filename": "fastapi_validation_i18n-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "160555a0c82a19b9050996eeddc8f28c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 25610,
"upload_time": "2025-08-12T02:57:28",
"upload_time_iso_8601": "2025-08-12T02:57:28.308976Z",
"url": "https://files.pythonhosted.org/packages/d8/9d/6211c8ff1c649ea6a8e22b362e61a8eb9545e1571eae21e07e995022fa13/fastapi_validation_i18n-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 02:57:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "whchi",
"github_project": "fastapi-validation-i18n",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastapi-validation-i18n"
}
JSON
