{"id":18773425,"url":"https://github.com/iosphere/elm-i18n","last_synced_at":"2025-07-07T00:09:16.649Z","repository":{"id":57222602,"uuid":"85641355","full_name":"iosphere/elm-i18n","owner":"iosphere","description":"Localization for Elm apps as a pre-build phase with import and export between elm code and CSV/PO ","archived":false,"fork":false,"pushed_at":"2019-05-03T14:49:35.000Z","size":128,"stargazers_count":71,"open_issues_count":12,"forks_count":6,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-19T23:11:39.627Z","etag":null,"topics":["csv","elm","i18n","language","po-files","translation"],"latest_commit_sha":null,"homepage":"","language":"Elm","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/iosphere.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-21T00:33:09.000Z","updated_at":"2024-11-19T14:36:49.000Z","dependencies_parsed_at":"2022-08-29T02:12:55.309Z","dependency_job_id":null,"html_url":"https://github.com/iosphere/elm-i18n","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/iosphere/elm-i18n","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iosphere%2Felm-i18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iosphere%2Felm-i18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iosphere%2Felm-i18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iosphere%2Felm-i18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iosphere","download_url":"https://codeload.github.com/iosphere/elm-i18n/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iosphere%2Felm-i18n/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261212082,"owners_count":23125560,"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":["csv","elm","i18n","language","po-files","translation"],"created_at":"2024-11-07T19:34:03.172Z","updated_at":"2025-07-07T00:09:16.615Z","avatar_url":"https://github.com/iosphere.png","language":"Elm","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n localization for Elm as a pre-build phase\n\n[![Travis](https://travis-ci.org/iosphere/elm-i18n.svg?branch=master)](https://travis-ci.org/iosphere/elm-i18n)\n[![npm version](https://badge.fury.io/js/elm-i18n.svg)](https://badge.fury.io/js/elm-i18n)\n\nelm-i18n provides tools and a concept for localizing elm apps. The idea is to\ntreat localized text as constants (or functions). To achieve this, localized\ncontent is placed in separate modules. Each language can consist of\nmultiple modules, but each module contains only one language.\n\n**The correct set of language modules is symlinked or copied into place before\ncompiling the elm app. The result is a localized compiled version of your app.**\nWhen repeating this process for multiple languages the compiler re-uses the\ncache and only the translation specific modules are cleared from the cache.\n\nThe elm-package is aimed at tool developers who want to parse elm-code into\nlocalized elements, read or write CSV or PO files. **If you want to use this\ntool for your elm-project you only need the information in this README.**\n\n## Features:\n\n* Switch languages:\n    * Switch the language of your elm app before building\n    * Easily build multiple localized version of your app\n*   `CSV \u003c-\u003e ELM \u003c-\u003e PO`\n    * Generate **CSV** and **PO** files from your localization module's elm code\n    * Generate your localization module's elm code from CSV and PO files\n\n\n\n## Suggested project file structure\n\nNote that the language identifier is only included in the directory name and\nexcluded from the Translation module names:\n\n```\nproject\n├── src/\n│   ├── Main.elm (e.g. imports Translation.Main)\n│   ├── View.elm (e.g. imports Translation.View)\n│   └──\u003eTranslation (sym-linked to current directory, e.g. project/Translation/De/)\n└── Translation/\n    ├── De/\n    │   ├── Main.elm (module Translation.Main)\n    │   └── View.elm (module Translation.View)\n    └── En/\n        ├── Main.elm (module Translation.Main)\n        └── View.elm (module Translation.View)\n```\n\n## Installation:\n\nThe tool-set is available as a node package and is backed by elm code:\n\n`npm install elm-i18n -g`\n\n## Switch language as a prebuild phase\n\nIn order to switch the language for compilation to `En`, simply execute the\nfollowing command at the root of your elm app:\n\n`elm-i18n-switch -l En`\n\nTo switch the language and compile a localized version of your app (to `dist/en.js`):\n\n`elm-i18n-switch -l En --output dist`\n\nIf your code is not stored in `src` or your main app module is not `Main.elm`:\n\n`elm-i18n-switch -l En --output dist --src myDir --elmFile MyMain.elm`\n\nIf your root `Translation` module is called `MyTranslation`:\n\n`elm-i18n-switch -l En --rootModule MyTranslation`\n\n\n## Codegen tools\n\nThis repository provides a few tools to extract string functions and constants\nfrom modules containing translations (where one language can consist of multiple\nmodules, but each module only contains one language).\n\n### CSV\n\n#### Export: Generate CSV from Elm source\n\n```bash\nelm-i18n-generator --format CSV --root example/Translation --language De --export\n```\n\nResult:\n\n```csv\nModule,Key,Comment,Supported Placeholders,Translation\n\"Translation.Main\",\"greeting\",\"A short greeting.\",\"\",\"Hi\"\n\"Translation.Main\",\"greetingWithName\",\"A personalized greeting. Use placeholder name for the user's name.\",\"name\",\"Guten Tag, {{name}}\"\n```\n\n#### Import: Generate Elm source code from CSV\n\n```bash\nelm-i18n-generator --format CSV -l De --import export.csv\n```\n\nResult in `import/De/Translation/Main.elm`:\n\n```elm\nmodule Translation.Main exposing (..)\n\n{-| -}\n\n\n{-| A short greeting.\n-}\ngreeting : String\ngreeting =\n    \"Hi\"\n\n\n{-| A personalized greeting. Use placeholder name for the user's name.\n-}\ngreetingWithName : String -\u003e String\ngreetingWithName name =\n    \"Guten Tag, \"\n        ++ name\n```\n\n### PO\n\nFor more information about the PO file format visit:\nhttps://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/PO-Files.html\n\n#### Export: Generate PO from Elm source:\n\n```bash\nelm-i18n-generator --format PO --root example/Translation --language De --export\n```\n\nResult:\n\n```po\n#. A short greeting.\nmsgid \"Translation.Main.greeting\"\nmsgstr \"Hi\"\n\n#. A personalized greeting. Use placeholder name for the user's name.\n#. i18n: placeholders: name\nmsgid \"Translation.Main.greetingWithName\"\nmsgstr \"Guten Tag, %(name)s\"\n```\n\n#### Import: Generate Elm source code from PO\n\n```bash\nelm-i18n-generator --format PO --language De --import export.po\n```\n\nResults in the same `import/De/Translation/Main.elm`\nas in the [CSV example](#import-generate-elm-source-code-from-csv).\n\n## Advantages\n\n+ Each build of your app only contains one language.\n+ No need to handle the current language in your elm app's model or view functions.\n+ You can use any logic you like for the text snippets: constants, functions...\n+ Allows you to create sub modules for parts of your app.\n+ Full type safety\n+ Auto completion (if you run the script at least once before starting the IDE).\n+ For testing you can add a Translation `Test` and set your code base to use\n  that before running tests. This way your tests do not change if you change the\n  wording of your buttons, labels and fallbacks.\n+ Compile-time errors for incomplete translations.\n+ Compile-time errors are limited to the incomplete language, so you can\n  continue shipping updates and fixes for the other languages.\n+ Get started with a new language quickly by exporting all strings for\n  an existing language, replacing all value in the CSV with \"TODO\" and then\n  import the CSV for the new language, which will create all `Translation`\n  modules.\n\n## Disadvantages\n\n- Language is no longer part of your view model and cannot be changed dynamically from within the app.\n  *However, you can add a constant with the current language code and have different code paths if that\n  is required.*\n- Language selection has to be handled outside of the elm-app (by loading the appropriate js artefact).\n\n[An issue has been created to address this disadvantage.](https://github.com/iosphere/elm-i18n/issues/2)\n\n## Building elm-i18n\n\nThe tool is built using node.js with an Elm-Core.\nTo build the elm backend of the node.js part (if developing locally):\n`make dist`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiosphere%2Felm-i18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiosphere%2Felm-i18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiosphere%2Felm-i18n/lists"}