# quick-i18n
**quick-i18n** is a simple and efficient internationalization (i18n) library for Python applications. It allows you to manage translations using JSON files, supports dynamic language switching, and provides formatting for translation strings.
## Features
- Simple setup and integration
- Supports multiple languages with dynamic switching
- Uses JSON files for storing translations
- Automatic handling of missing translations in development mode
- Supports positional and keyword arguments for string formatting
- Domain separation for organizing translations
- Customizable translation directories
## Installation
Install the package via pip:
```bash
pip install quick-i18n
```
## Usage
```python
from quicki18n import i18n
# Initialize the i18n class
t = i18n(
languages=['en', 'es'],
default_language='en',
default_domain="default",
dev_mode=True # Set to False in production
)
# Set the current language
t.set_language('es')
# Get translations
print(t('Welcome to our application!')) # Translates based on the current language
# Use formatting in translations
print(t('Greeting, {name}', name='Alice', domain='messages'))
```
After execution quick-i18n generate for You json files:
```json
{
"default": {
"welcome-to-our-application": "Welcome to our application!"
},
"messages": {
"greeting-name": "Greeting, {name}!"
}
}
```
## Development Mode
When dev_mode is set to True, missing translation keys are automatically added to all language files,
making it easier to manage translations during development.
## Recommendations for organizing file structure
When integrating the quick-i18n package into your Python project, it's important to organize your files and
directories effectively to ensure maintainability and scalability. This guide provides recommendations for
structuring your project to make the most out of quick-i18n.
### Project Structure
A well-organized project structure enhances readability and maintainability. Here's a recommended structure
when using quick-i18n:
```scss
your_project/
├── app/
│ ├── __init__.py
│ ├── i18n.py
│ ├── main.py
│ └── ... (other modules)
├── translations/
│ ├── en.json
│ ├── es.json
│ ├── ru.json
│ └── ... (other language files)
├── requirements.txt
├── README.md
└── ... (other files)
```
- `app/`: Contains your application code.
- `translations/`: Stores your translation JSON files.
- `requirements.txt`: Lists your project dependencies.
- `README.md`: Provides information about your project.
### Translation Files
Place or generate your translation files in a dedicated translations/
directory at the root of your project. Each language has its own
JSON file named after its language code (e.g., en.json for English).
Example en.json:
```json
{
"default": {
"welcome": "Welcome to our application!",
"farewell": "Goodbye, {name}!"
},
"errors": {
"not_found": "The requested item was not found.",
"unauthorized": "You are not authorized to perform this action."
}
}
```
es.json
```json
{
"default": {
"welcome": "¡Bienvenido a nuestra aplicación!",
"farewell": "¡Adiós, {name}!"
},
"errors": {
"not_found": "El elemento solicitado no fue encontrado.",
"unauthorized": "No estás autorizado para realizar esta acción."
}
}
```
### Initializing quick-i18n
Initialize quick-i18n in a central location within your application, such as the __init__.py file of your app/ package
or a dedicated module (e.g., app/i18n.py).
```python
# app/i18n.py
import os
from quicki18n import i18n
# Determine the path to the translations directory
translations_path = os.path.join(os.path.dirname(__file__), '..', 'translations')
# Initialize the i18n instance
t = i18n(
languages=['en', 'es', 'ru'],
default_language='en',
dev_mode=False, # Set to True during development
translations_path=translations_path
)
```
- languages: List of supported language codes.
- current_language: Default language for your application.
- dev_mode: When True, missing translation keys are added automatically.
- translations_path: Path to your translations/ directory.
### Using Translations in Your Code
Import the translation instance t and use it to fetch translations within your application modules.
```python
# app/main.py
from . import t
def greet_user(name):
welcome_message = t('default.welcome')
personalized_farewell = t('default.farewell', name=name)
print(welcome_message)
print(personalized_farewell)
if __name__ == "__main__":
t.set_language('es') # Set language to Spanish
greet_user('Carlos')
```
Output:
```css
¡Bienvenido a nuestra aplicación!
¡Adiós, Carlos!
```
## Best Practices
1. **Consistent Key Naming:**
Use dot notation to organize translation keys into namespaces (e.g., default.welcome, errors.not_found).
Keep key names consistent across all language files.
2. **Placeholder Usage:**
Use placeholders for dynamic content in your translations.
Support both positional ({}) and keyword ({name}) placeholders.
Ensure placeholders are consistent in all translations for a key.
3. **Language Codes:**
Use standard ISO 639-1 language codes (e.g., en for English, es for Spanish).
This ensures compatibility and clarity.
4. **Development Mode:**
Enable dev_mode during development to automatically add missing keys.
Remember to disable dev_mode in production to prevent unintended file modifications.
5. **Translation Updates:**
When adding new translations, update all language files to keep them in sync.
Use empty strings or the original text as placeholders until translations are available.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
Contributions are welcome! Please submit a pull request or open an issue for any improvements or bug fixes.
Raw data
{
"_id": null,
"home_page": "https://github.com/urands/quick-i18n",
"name": "quick-i18n",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "i18n, internationalization, translation, localization, python",
"author": "Iu Bell",
"author_email": "Iu Bell <uran.ds@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fc/e8/74d5ffe5d759a95f6a7d90f7bc3164ebe1e966d55e84ee6ab9f2f807d033/quick_i18n-0.1.2.tar.gz",
"platform": null,
"description": "# quick-i18n\r\n\r\n**quick-i18n** is a simple and efficient internationalization (i18n) library for Python applications. It allows you to manage translations using JSON files, supports dynamic language switching, and provides formatting for translation strings.\r\n\r\n## Features\r\n\r\n- Simple setup and integration\r\n- Supports multiple languages with dynamic switching\r\n- Uses JSON files for storing translations\r\n- Automatic handling of missing translations in development mode\r\n- Supports positional and keyword arguments for string formatting\r\n- Domain separation for organizing translations\r\n- Customizable translation directories\r\n\r\n## Installation\r\n\r\nInstall the package via pip:\r\n\r\n```bash\r\npip install quick-i18n\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nfrom quicki18n import i18n\r\n\r\n# Initialize the i18n class\r\nt = i18n(\r\n languages=['en', 'es'],\r\n default_language='en',\r\n default_domain=\"default\",\r\n dev_mode=True # Set to False in production\r\n)\r\n\r\n# Set the current language\r\nt.set_language('es')\r\n\r\n# Get translations\r\nprint(t('Welcome to our application!')) # Translates based on the current language\r\n\r\n# Use formatting in translations\r\nprint(t('Greeting, {name}', name='Alice', domain='messages'))\r\n```\r\n\r\nAfter execution quick-i18n generate for You json files:\r\n\r\n```json\r\n{\r\n \"default\": {\r\n \"welcome-to-our-application\": \"Welcome to our application!\"\r\n },\r\n \"messages\": {\r\n \"greeting-name\": \"Greeting, {name}!\"\r\n }\r\n}\r\n```\r\n\r\n## Development Mode\r\n\r\nWhen dev_mode is set to True, missing translation keys are automatically added to all language files,\r\nmaking it easier to manage translations during development.\r\n\r\n\r\n## Recommendations for organizing file structure\r\n\r\nWhen integrating the quick-i18n package into your Python project, it's important to organize your files and\r\ndirectories effectively to ensure maintainability and scalability. This guide provides recommendations for \r\nstructuring your project to make the most out of quick-i18n.\r\n\r\n### Project Structure\r\n\r\nA well-organized project structure enhances readability and maintainability. Here's a recommended structure \r\nwhen using quick-i18n:\r\n```scss\r\nyour_project/\r\n\u251c\u2500\u2500 app/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 i18n.py\r\n\u2502 \u251c\u2500\u2500 main.py\r\n\u2502 \u2514\u2500\u2500 ... (other modules)\r\n\u251c\u2500\u2500 translations/\r\n\u2502 \u251c\u2500\u2500 en.json\r\n\u2502 \u251c\u2500\u2500 es.json\r\n\u2502 \u251c\u2500\u2500 ru.json\r\n\u2502 \u2514\u2500\u2500 ... (other language files)\r\n\u251c\u2500\u2500 requirements.txt\r\n\u251c\u2500\u2500 README.md\r\n\u2514\u2500\u2500 ... (other files)\r\n```\r\n- `app/`: Contains your application code.\r\n- `translations/`: Stores your translation JSON files.\r\n- `requirements.txt`: Lists your project dependencies.\r\n- `README.md`: Provides information about your project.\r\n\r\n### Translation Files\r\n\r\nPlace or generate your translation files in a dedicated translations/ \r\ndirectory at the root of your project. Each language has its own \r\nJSON file named after its language code (e.g., en.json for English).\r\n\r\nExample en.json:\r\n```json\r\n{\r\n \"default\": {\r\n \"welcome\": \"Welcome to our application!\",\r\n \"farewell\": \"Goodbye, {name}!\"\r\n },\r\n \"errors\": {\r\n \"not_found\": \"The requested item was not found.\",\r\n \"unauthorized\": \"You are not authorized to perform this action.\"\r\n }\r\n}\r\n```\r\n\r\nes.json\r\n```json\r\n{\r\n \"default\": {\r\n \"welcome\": \"\u00a1Bienvenido a nuestra aplicaci\u00f3n!\",\r\n \"farewell\": \"\u00a1Adi\u00f3s, {name}!\"\r\n },\r\n \"errors\": {\r\n \"not_found\": \"El elemento solicitado no fue encontrado.\",\r\n \"unauthorized\": \"No est\u00e1s autorizado para realizar esta acci\u00f3n.\"\r\n }\r\n}\r\n\r\n\r\n```\r\n\r\n### Initializing quick-i18n\r\nInitialize quick-i18n in a central location within your application, such as the __init__.py file of your app/ package \r\nor a dedicated module (e.g., app/i18n.py).\r\n\r\n```python \r\n# app/i18n.py\r\n\r\nimport os\r\nfrom quicki18n import i18n\r\n\r\n# Determine the path to the translations directory\r\ntranslations_path = os.path.join(os.path.dirname(__file__), '..', 'translations')\r\n\r\n# Initialize the i18n instance\r\nt = i18n(\r\n languages=['en', 'es', 'ru'],\r\n default_language='en',\r\n dev_mode=False, # Set to True during development\r\n translations_path=translations_path\r\n)\r\n```\r\n- languages: List of supported language codes.\r\n- current_language: Default language for your application.\r\n- dev_mode: When True, missing translation keys are added automatically.\r\n- translations_path: Path to your translations/ directory.\r\n\r\n### Using Translations in Your Code\r\nImport the translation instance t and use it to fetch translations within your application modules.\r\n\r\n```python\r\n# app/main.py\r\n\r\nfrom . import t\r\n\r\ndef greet_user(name):\r\n welcome_message = t('default.welcome')\r\n personalized_farewell = t('default.farewell', name=name)\r\n print(welcome_message)\r\n print(personalized_farewell)\r\n\r\nif __name__ == \"__main__\":\r\n t.set_language('es') # Set language to Spanish\r\n greet_user('Carlos')\r\n\r\n\r\n```\r\n\r\nOutput:\r\n```css\r\n\u00a1Bienvenido a nuestra aplicaci\u00f3n!\r\n\u00a1Adi\u00f3s, Carlos!\r\n```\r\n## Best Practices\r\n1. **Consistent Key Naming:**\r\nUse dot notation to organize translation keys into namespaces (e.g., default.welcome, errors.not_found).\r\nKeep key names consistent across all language files.\r\n2. **Placeholder Usage:**\r\nUse placeholders for dynamic content in your translations.\r\nSupport both positional ({}) and keyword ({name}) placeholders.\r\nEnsure placeholders are consistent in all translations for a key.\r\n3. **Language Codes:**\r\nUse standard ISO 639-1 language codes (e.g., en for English, es for Spanish).\r\nThis ensures compatibility and clarity.\r\n4. **Development Mode:**\r\nEnable dev_mode during development to automatically add missing keys.\r\nRemember to disable dev_mode in production to prevent unintended file modifications.\r\n5. **Translation Updates:**\r\nWhen adding new translations, update all language files to keep them in sync.\r\nUse empty strings or the original text as placeholders until translations are available.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please submit a pull request or open an issue for any improvements or bug fixes.\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A quick and easy internationalization library for Python.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/urands/quick-i18n#readme",
"Homepage": "https://github.com/urands/quick-i18n",
"Source": "https://github.com/urands/quick-i18n",
"Tracker": "https://github.com/urands/quick-i18n/issues"
},
"split_keywords": [
"i18n",
" internationalization",
" translation",
" localization",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5e101a96b514a7b3501862ffe4b89f8e029770cbb9db491432da034b4f7052ee",
"md5": "135ce20c17a8d9951614110076038f3b",
"sha256": "36d5633997db22239607dacea40fbbd2941ecf1ec6c7e9834cc4e2de9a74cf0d"
},
"downloads": -1,
"filename": "quick_i18n-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "135ce20c17a8d9951614110076038f3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6307,
"upload_time": "2024-10-06T11:05:39",
"upload_time_iso_8601": "2024-10-06T11:05:39.640969Z",
"url": "https://files.pythonhosted.org/packages/5e/10/1a96b514a7b3501862ffe4b89f8e029770cbb9db491432da034b4f7052ee/quick_i18n-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fce874d5ffe5d759a95f6a7d90f7bc3164ebe1e966d55e84ee6ab9f2f807d033",
"md5": "90c10f05f531bc687413e66805b5574e",
"sha256": "006c13134c32172ad9f868a7f9dd16ab1613dab9f2b10438c095997084dbdacb"
},
"downloads": -1,
"filename": "quick_i18n-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "90c10f05f531bc687413e66805b5574e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6287,
"upload_time": "2024-10-06T11:05:42",
"upload_time_iso_8601": "2024-10-06T11:05:42.399099Z",
"url": "https://files.pythonhosted.org/packages/fc/e8/74d5ffe5d759a95f6a7d90f7bc3164ebe1e966d55e84ee6ab9f2f807d033/quick_i18n-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-06 11:05:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "urands",
"github_project": "quick-i18n",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quick-i18n"
}
JSON
