# LocoJSON
LocoJSON is a brand new library for multilingual support in Python programs, designed to be the lightest possible. It uses only the standard library and has no external dependencies.
However, LocoJSON depends on a core library called [LocoCore](https://github.com/drago-suzuki58/LocoCore). LocoCore provides common multilingual support features, and LocoJSON adds JSON-based translation functionality on top of it.
Other Language LEADME (GitHub)
[Japanese](https://github.com/drago-suzuki58/LocoJSON/blob/main/README.ja.md)
## Features
- **Easy Calls**:
You can easily call translations by writing `loc.key1.key2.key3()`, improving code readability. For more details, please refer to the documentation.
- **Flexible Calls**:
If you want to output in English just this time, you can temporarily change the language by writing `loc.key1("en")`.
- **Easy-to-understand JSON Translations**:
Translations are in JSON format, making it easy to load files corresponding to each language.
- **Hierarchical Translation Structure**:
You can handle multiple keys hierarchically, such as `key1.key2.key3`, making it comfortable to use even when the data grows.
- **Detailed Log Output**:
When translation keys are incomplete or errors occur, detailed logs including the file name and line number of the relevant part are output, making troubleshooting easy.
- **Fallback**:
If a translation corresponding to the language is not found, it automatically falls back to the default language set. If there is no translation at all, the translation ID is output as is, clearly notifying the developer.
## Installation
Install from PyPI
```sh
pip install locojson
```
Alternatively, you can install it from the GitHub repository:
```sh
python -m pip install git+https://github.com/drago-suzuki58/LocoJSON
```
## Sample Code
Basic Usage
`main.py`
```python
from locojson import LocoJSON
# Set the default language to Japanese and the fallback language to English
loc = LocoJSON(locale="ja", fallback_locale="en", locale_dir="loc")
# こんにちは
print(loc.greeting.hello())
# こんにちは！太郎さん
print(loc.greeting.hello_to_user(user="太郎"))
```
Temporarily Specify Language for Translation
`main.py`
```python
# Hello
print(loc.greeting.hello("en"))
# Hello! John
print(loc.greeting.hello_to_user("en", user="John"))
```
Fallback Example
t notifies the relevant line and file name where it was called, supporting development.
`main.py`
```python
# Log: 2024-11-17 20:23:03 | WARNING | main.py:18 - Missing translation: greeting.hello in: fr, return key name
# Hello
print(loc.greeting.hello("fr")) # Non-existent translation language
# Log: 2024-11-17 20:23:03 | WARNING | main.py:23 - Missing translation: greeting.goodbye in: ja, falling back to en
# Log: 2024-11-17 20:23:03 | WARNING | main.py:25 - Missing translation: greeting.goodbye in: en, return key name
# greeting.goodbye
print(loc.greeting.goodbye())
```
Unused Arguments Example
It notifies the relevant line and file name in the log, similar to fallback.
`main.py`
```python
# Log: 2024-11-17 20:23:03 | WARNING | main.py:29 - Unused keys: {'message': 'hogehoge'}
# こんにちは
print(loc.greeting.hello(message="hogehoge"))
```
Translation Files Used in `main.py`
`loc/ja.json`
```json
{
"greeting" : {
"hello" : "こんにちは",
"hello_to_user" : "こんにちは！{user}さん"
},
"sample" : "サンプル"
}
```
`loc/en.json`
```json
{
"greeting" : {
"hello" : "Hello",
"hello_to_user" : "Hello! {user}"
},
"sample" : "Sample"
}
```
In addition to the above sample code, practical examples are available in the [example](https://github.com/drago-suzuki58/LocoJSON/tree/main/examples) folder. Please take a look.
## Q&A
### What language codes should I use for translations?
Basically, you are free to use any language code as long as it matches the JSON file name. (Even `UwU.json` will be recognized correctly!) However, for readability, we recommend using standard formats such as ISO 639-1 (`en`, etc.) or ISO-3166 (`US`).
### Are default and fallback languages required?
The default language is required, but the fallback language is not. If not set, `en` will be automatically set as the fallback language.
### Can I use formats other than JSON (e.g., YAML)?
No, currently only JSON is supported. If there is high demand, we may develop a separate library like LocoYAML.
## Contribution
LocoJSON is an open-source project! Bug reports and feature suggestions are welcome.
TOML is currently available at [LocoTOML](https://github.com/drago-suzuki58/LocoTOML).
## Update Info
<details>
<summary>Click to show update information</summary>
### v0.1.0
- Initial release
### v0.2.0
- Separating the core code for greater flexibility
</details>
Raw data
{
"_id": null,
"home_page": "https://github.com/drago-suzuki58/LocoJSON",
"name": "locojson",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "json, localization, translation, localisation, multi-language",
"author": "drago-suzuki58",
"author_email": "dorasuzu58@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5d/97/195c69479913c7d728ead1231b1c7a2fb5352ba844d88e4834478212646f/locojson-0.2.1.tar.gz",
"platform": null,
"description": "# LocoJSON\n\nLocoJSON is a brand new library for multilingual support in Python programs, designed to be the lightest possible. It uses only the standard library and has no external dependencies.\n\nHowever, LocoJSON depends on a core library called [LocoCore](https://github.com/drago-suzuki58/LocoCore). LocoCore provides common multilingual support features, and LocoJSON adds JSON-based translation functionality on top of it.\n\nOther Language LEADME (GitHub)\n[Japanese](https://github.com/drago-suzuki58/LocoJSON/blob/main/README.ja.md)\n\n## Features\n\n- **Easy Calls**:\n\n You can easily call translations by writing `loc.key1.key2.key3()`, improving code readability. For more details, please refer to the documentation.\n\n- **Flexible Calls**:\n\n If you want to output in English just this time, you can temporarily change the language by writing `loc.key1(\"en\")`.\n\n- **Easy-to-understand JSON Translations**:\n\n Translations are in JSON format, making it easy to load files corresponding to each language.\n\n- **Hierarchical Translation Structure**:\n\n You can handle multiple keys hierarchically, such as `key1.key2.key3`, making it comfortable to use even when the data grows.\n\n- **Detailed Log Output**:\n\n When translation keys are incomplete or errors occur, detailed logs including the file name and line number of the relevant part are output, making troubleshooting easy.\n\n- **Fallback**:\n\n If a translation corresponding to the language is not found, it automatically falls back to the default language set. If there is no translation at all, the translation ID is output as is, clearly notifying the developer.\n\n## Installation\n\nInstall from PyPI\n\n```sh\npip install locojson\n```\n\nAlternatively, you can install it from the GitHub repository:\n\n```sh\npython -m pip install git+https://github.com/drago-suzuki58/LocoJSON\n```\n\n## Sample Code\n\nBasic Usage\n\n`main.py`\n```python\nfrom locojson import LocoJSON\n\n# Set the default language to Japanese and the fallback language to English\nloc = LocoJSON(locale=\"ja\", fallback_locale=\"en\", locale_dir=\"loc\")\n\n# \u3053\u3093\u306b\u3061\u306f\nprint(loc.greeting.hello())\n\n# \u3053\u3093\u306b\u3061\u306f\uff01\u592a\u90ce\u3055\u3093\nprint(loc.greeting.hello_to_user(user=\"\u592a\u90ce\"))\n```\n\nTemporarily Specify Language for Translation\n\n`main.py`\n```python\n# Hello\nprint(loc.greeting.hello(\"en\"))\n\n# Hello! John\nprint(loc.greeting.hello_to_user(\"en\", user=\"John\"))\n```\n\nFallback Example\nt notifies the relevant line and file name where it was called, supporting development.\n\n`main.py`\n```python\n# Log: 2024-11-17 20:23:03 | WARNING | main.py:18 - Missing translation: greeting.hello in: fr, return key name\n# Hello\nprint(loc.greeting.hello(\"fr\")) # Non-existent translation language\n\n# Log: 2024-11-17 20:23:03 | WARNING | main.py:23 - Missing translation: greeting.goodbye in: ja, falling back to en\n# Log: 2024-11-17 20:23:03 | WARNING | main.py:25 - Missing translation: greeting.goodbye in: en, return key name\n# greeting.goodbye\nprint(loc.greeting.goodbye())\n```\n\nUnused Arguments Example\nIt notifies the relevant line and file name in the log, similar to fallback.\n\n`main.py`\n```python\n# Log: 2024-11-17 20:23:03 | WARNING | main.py:29 - Unused keys: {'message': 'hogehoge'}\n# \u3053\u3093\u306b\u3061\u306f\nprint(loc.greeting.hello(message=\"hogehoge\"))\n```\n\nTranslation Files Used in `main.py`\n\n`loc/ja.json`\n```json\n{\n \"greeting\" : {\n \"hello\" : \"\u3053\u3093\u306b\u3061\u306f\",\n \"hello_to_user\" : \"\u3053\u3093\u306b\u3061\u306f\uff01{user}\u3055\u3093\"\n },\n \"sample\" : \"\u30b5\u30f3\u30d7\u30eb\"\n}\n```\n\n`loc/en.json`\n```json\n{\n \"greeting\" : {\n \"hello\" : \"Hello\",\n \"hello_to_user\" : \"Hello! {user}\"\n },\n \"sample\" : \"Sample\"\n}\n```\n\nIn addition to the above sample code, practical examples are available in the [example](https://github.com/drago-suzuki58/LocoJSON/tree/main/examples) folder. Please take a look.\n\n## Q&A\n\n### What language codes should I use for translations?\n\nBasically, you are free to use any language code as long as it matches the JSON file name. (Even `UwU.json` will be recognized correctly!) However, for readability, we recommend using standard formats such as ISO 639-1 (`en`, etc.) or ISO-3166 (`US`).\n\n### Are default and fallback languages required?\n\nThe default language is required, but the fallback language is not. If not set, `en` will be automatically set as the fallback language.\n\n### Can I use formats other than JSON (e.g., YAML)?\n\nNo, currently only JSON is supported. If there is high demand, we may develop a separate library like LocoYAML.\n\n## Contribution\n\nLocoJSON is an open-source project! Bug reports and feature suggestions are welcome.\nTOML is currently available at [LocoTOML](https://github.com/drago-suzuki58/LocoTOML).\n\n## Update Info\n\n<details>\n<summary>Click to show update information</summary>\n\n### v0.1.0\n\n- Initial release\n\n### v0.2.0\n\n- Separating the core code for greater flexibility\n\n</details>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "LocoJSON is a lightweight Python library for multi-language support, using hierarchical JSON-based translations with fallback and detailed logging for missing keys.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/drago-suzuki58/LocoJSON",
"Issues": "https://github.com/drago-suzuki58/LocoJSON/issues",
"Repository": "https://github.com/drago-suzuki58/LocoJSON"
},
"split_keywords": [
"json",
" localization",
" translation",
" localisation",
" multi-language"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "848a6c9816c5c5622e119a1aece8bdad04468425ebbac7b40d73b1deaf730b80",
"md5": "5095b3955b0c4d99625cf35960d57d87",
"sha256": "6f9b4d20c6635e1e2a9c4a2e53de79fb7a30c6619c314f2294248283166b741a"
},
"downloads": -1,
"filename": "locojson-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5095b3955b0c4d99625cf35960d57d87",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 4726,
"upload_time": "2024-11-20T19:27:47",
"upload_time_iso_8601": "2024-11-20T19:27:47.261510Z",
"url": "https://files.pythonhosted.org/packages/84/8a/6c9816c5c5622e119a1aece8bdad04468425ebbac7b40d73b1deaf730b80/locojson-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d97195c69479913c7d728ead1231b1c7a2fb5352ba844d88e4834478212646f",
"md5": "f8df4ba10ef06adecbf0c90ecf416370",
"sha256": "26fddec8b1193c5608b15b9992f02f7ac00df0be57a2b65dd1c361fec921556d"
},
"downloads": -1,
"filename": "locojson-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "f8df4ba10ef06adecbf0c90ecf416370",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 4181,
"upload_time": "2024-11-20T19:27:48",
"upload_time_iso_8601": "2024-11-20T19:27:48.290924Z",
"url": "https://files.pythonhosted.org/packages/5d/97/195c69479913c7d728ead1231b1c7a2fb5352ba844d88e4834478212646f/locojson-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 19:27:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drago-suzuki58",
"github_project": "LocoJSON",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "locojson"
}
JSON
