{"id":16085535,"url":"https://github.com/Insality/defold-lang","last_synced_at":"2025-10-23T02:30:43.666Z","repository":{"id":251112427,"uuid":"836407450","full_name":"Insality/defold-lang","owner":"Insality","description":"Defold Localization Helper","archived":false,"fork":false,"pushed_at":"2024-11-12T20:15:23.000Z","size":757,"stargazers_count":21,"open_issues_count":4,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T08:45:29.406Z","etag":null,"topics":["defold","defold-extension","defold-module","localization"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Insality.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"insality","ko_fi":"insality","buy_me_a_coffee":"insality"}},"created_at":"2024-07-31T19:30:42.000Z","updated_at":"2025-02-05T22:54:33.000Z","dependencies_parsed_at":"2024-10-23T05:05:58.357Z","dependency_job_id":"227cb772-c1b4-492c-917a-829d0e433c29","html_url":"https://github.com/Insality/defold-lang","commit_stats":{"total_commits":12,"total_committers":1,"mean_commits":12.0,"dds":0.0,"last_synced_commit":"03d9060fa1071cd55cf5a308bda35ee49e4d384f"},"previous_names":["insality/defold-lang"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-lang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-lang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-lang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Insality%2Fdefold-lang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Insality","download_url":"https://codeload.github.com/Insality/defold-lang/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237763855,"owners_count":19362310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-extension","defold-module","localization"],"created_at":"2024-10-09T13:02:00.846Z","updated_at":"2025-10-23T02:30:43.660Z","avatar_url":"https://github.com/Insality.png","language":"Lua","funding_links":["https://github.com/sponsors/insality","https://ko-fi.com/insality","https://buymeacoffee.com/insality","https://www.buymeacoffee.com/insality"],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![](media/logo.png)\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/tag/insality/defold-lang?style=for-the-badge\u0026label=Release)](https://github.com/Insality/defold-lang/tags)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/insality/defold-lang/ci_workflow.yml?style=for-the-badge)](https://github.com/Insality/defold-lang/actions)\n[![codecov](https://img.shields.io/codecov/c/github/Insality/defold-lang?style=for-the-badge)](https://codecov.io/gh/Insality/defold-lang)\n\n[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/insality) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/insality) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/insality)\n\n\n# Defold Lang\n\n**Defold Lang** is a simple localization module for **Defold**. It loads language files and manages translations in your project.\n\n## Features\n\n- **Handy API** - Simple and easy to use API\n- **Multiple File Formats** - Support for JSON, Lua, and CSV language files\n- **Saver Support** - Save current selected language in [Defold-Saver](https://github.com/Insality/defold-saver)\n- **Druid Support** - Easy [Druid](https://github.com/Insality/druid) integration\n\n## Setup\n\n### [Dependency](https://www.defold.com/manuals/libraries/)\n\nOpen your `game.project` file and add the following line to the dependencies field under the project section:\n\n**[Lang](https://github.com/Insality/defold-lang/archive/refs/tags/4.zip)**\n\n```\nhttps://github.com/Insality/defold-lang/archive/refs/tags/4.zip\n```\n\nAfter that, select `Project ▸ Fetch Libraries` to update [library dependencies]((https://defold.com/manuals/libraries/#setting-up-library-dependencies)). This happens automatically whenever you open a project so you will only need to do this if the dependencies change without re-opening the project.\n\n### Library Size\n\n\u003e **Note:** The library size is calculated based on the build report per platform\n\n| Platform         | Library Size |\n| ---------------- | ------------ |\n| HTML5            | **7.87 KB**  |\n| Desktop / Mobile | **12.68 KB**  |\n\n\n### Initialization\n\nInitialize the **Lang** module by calling `lang.init()` with your language configuration:\n\n```lua\nlocal lang = require(\"lang.lang\")\n\n-- Initialize with language files\nlang.init({\n\t{ id = \"en\", path = \"/resources/lang/en.json\" },\n\t{ id = \"ru\", path = \"/resources/lang/ru.json\" },\n\t{ id = \"es\", path = \"/resources/lang/es.json\" },\n})\n```\n\nYou can also force a specific language on initialization:\n\n```lua\n-- Force a specific language on start\nlang.init({\n\t{ id = \"en\", path = \"/resources/lang/en.json\" },\n\t{ id = \"ru\", path = \"/resources/lang/ru.json\" },\n\t{ id = \"es\", path = \"/resources/lang/es.json\" },\n}, \"es\") -- Force Spanish language\n```\n\n\n### Default Language\n\n**Defold Lang** selects the language to use in the following priority order:\n\n1. **Force parameter** - If provided as second parameter to `lang.init()`\n2. **Saved language** - From `lang.state.lang` (restored from save system or manually set)\n3. **System language** - Device language from `sys.get_sys_info().language`\n4. **Default language** - First language in the configuration array\n\nThe first language in the configuration array serves as the ultimate fallback. Defold uses the two-character [ISO-639 format](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for language codes (\"en\", \"ru\", \"es\", etc).\n\nThe module uses `sys.load_resource` to load the files. Place your files inside your [custom resources folder](https://defold.com/manuals/project-settings/#custom-resources) to ensure they are included in the build.\n\n\n### Localization Files\n\n**Defold Lang** supports three file formats: **JSON**, **Lua**, and **CSV**. Each format has its own advantages:\n\n#### JSON Files\nJSON files use a simple key-value structure:\n\n```json\n{\n\t\"ui_hello_world\": \"Hello, World!\",\n\t\"ui_hello_name\": \"Hello, %s!\",\n\t\"ui_settings\": \"Settings\",\n\t\"ui_exit\": \"Exit\"\n}\n```\n\nInitialize with JSON files:\n```lua\nlang.init({\n\t{ id = \"en\", path = \"/locales/en.json\" },\n\t{ id = \"ru\", path = \"/locales/ru.json\" },\n\t{ id = \"es\", path = \"/locales/es.json\" },\n})\n```\n\n#### Lua Files\nLua files return a table with translations:\n\n```lua\n-- en.lua\nreturn {\n\tui_hello_world = \"Hello, World!\",\n\tui_hello_name = \"Hello, %s!\",\n\tui_settings = \"Settings\",\n\tui_exit = \"Exit\"\n}\n```\n\nInitialize with Lua files:\n```lua\nlang.init({\n\t{ id = \"en\", path = require(\"locales.en\") },\n\t{ id = \"ru\", path = require(\"locales.ru\") },\n\t{ id = \"es\", path = require(\"locales.es\") },\n})\n```\n\n#### CSV Files\nCSV files allow multiple languages in a single file. The first column contains keys, and subsequent columns contain translations:\n\n```csv\nkey,en,ru,es\nui_hello_world,\"Hello, World!\",\"Привет, мир!\",\"¡Hola, mundo!\"\nui_hello_name,\"Hello, %s!\",\"Привет, %s!\",\"¡Hola, %s!\"\nui_settings,Settings,Настройки,Configuración\nui_exit,Exit,Выход,Salir\n```\n\nInitialize with CSV files (specify column names as language IDs):\n```lua\nlang.init({\n\t{ id = \"en\", path = \"/locales/translations.csv\" },\n\t{ id = \"ru\", path = \"/locales/translations.csv\" },\n\t{ id = \"es\", path = \"/locales/translations.csv\" },\n})\n```\n\n#### Mixed Format Example\nYou can even mix different file formats:\n\n```lua\nlang.init({\n\t{ id = \"en\", path = \"/resources/lang/en.json\" },\n\t{ id = \"ru\", path = \"/resources/lang/ru.lua\" },\n\t{ id = \"es\", path = \"/resources/lang/translations.csv\" },\n})\n```\n\n\n## API Reference\n\n### Quick API Reference\n\n```lua\nlang.init(available_langs, [lang_on_start])\nlang.set_lang(lang_id)\nlang.get_lang()\nlang.get_langs()\nlang.set_next_lang()\nlang.get_next_lang()\nlang.txt(text_id)\nlang.txp(text_id, ...)\nlang.txr(text_id)\nlang.is_exist(text_id)\nlang.set_logger([logger])\nlang.reset_state()\n```\n\n#### Basic Usage Example\n\n```lua\nlocal lang = require(\"lang.lang\")\n\n-- Initialize with language files\nlang.init({\n\t{ id = \"en\", path = \"/resources/lang/en.json\" },\n\t{ id = \"ru\", path = \"/resources/lang/ru.json\" },\n\t{ id = \"es\", path = \"/resources/lang/es.json\" },\n})\n\n-- Use translations\nprint(lang.txt(\"ui_hello_world\"))     -- \"Hello, World!\"\nprint(lang.txp(\"ui_hello_name\", \"John\")) -- \"Hello, John!\"\n\n-- Change language\nlang.set_lang(\"es\")\nprint(lang.txt(\"ui_hello_world\"))     -- \"¡Hola, mundo!\"\n```\n\n### API Reference\n\nRead the [API Reference](API_REFERENCE.md) file to see the full API documentation for the module.\n\n\n## Use Cases\n\nRead the [Use Cases](USE_CASES.md) file to see several examples of how to use the this module in your Defold game development projects.\n\n\n## FAQ\n\nRead the [FAQ](FAQ.md) file to see the answers to frequently asked questions about the module.\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n## Issues and Suggestions\n\nFor any issues, questions, or suggestions, please [create an issue](https://github.com/Insality/defold-lang/issues).\n\n\n## 👏 Contributors\n\n\u003ca href=\"https://github.com/Insality/defold-lang/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=insality/defold-lang\"/\u003e\n\u003c/a\u003e\n\n## Changelog\n\n\u003cdetails\u003e\n\n### **V1**\n\t- Initial release\n\n### **V2**\n\t- Add Defold Editor Script to collect unique characters from selected JSON files\n\n### **V3**\n\t- Add `lang.get_next_lang()` function\n\t- Better error messages\n\n### **V4**\n\t- [Breaking] Lang now use `lang.init()` function to initialize module instead of `game.project` configuration\n\t- Add Lua file support\n\t- Add CSV file support\n\t- Updated editor script to collect unique characters from selected JSON and CSV files\n\t- Add Lang debug properties page for Druid properties panel\n\n\u003c/details\u003e\n\n\n## ❤️ Support project ❤️\n\nYour donation helps me stay engaged in creating valuable projects for **Defold**. If you appreciate what I'm doing, please consider supporting me!\n\n[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge\u0026logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/insality) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/insality) [![BuyMeACoffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge\u0026logo=buy-me-a-coffee\u0026logoColor=black)](https://www.buymeacoffee.com/insality)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInsality%2Fdefold-lang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FInsality%2Fdefold-lang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FInsality%2Fdefold-lang/lists"}