{"id":36919191,"url":"https://github.com/donseba/go-translator","last_synced_at":"2026-01-12T16:13:14.542Z","repository":{"id":220055219,"uuid":"740197720","full_name":"donseba/go-translator","owner":"donseba","description":"Dynamic localization of applications","archived":false,"fork":false,"pushed_at":"2025-06-02T19:31:07.000Z","size":54,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-01T22:12:12.061Z","etag":null,"topics":["gettext","localization","plural","translation"],"latest_commit_sha":null,"homepage":"","language":"Go","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/donseba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-01-07T19:57:51.000Z","updated_at":"2025-06-02T19:30:49.000Z","dependencies_parsed_at":"2024-03-25T09:27:32.337Z","dependency_job_id":"c13c37e9-557c-4164-a91f-f39eb970574c","html_url":"https://github.com/donseba/go-translator","commit_stats":null,"previous_names":["donseba/go-translator"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/donseba/go-translator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donseba%2Fgo-translator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donseba%2Fgo-translator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donseba%2Fgo-translator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donseba%2Fgo-translator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donseba","download_url":"https://codeload.github.com/donseba/go-translator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donseba%2Fgo-translator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28342221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T15:50:39.657Z","status":"ssl_error","status_checked_at":"2026-01-12T15:49:49.297Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["gettext","localization","plural","translation"],"created_at":"2026-01-12T16:13:14.468Z","updated_at":"2026-01-12T16:13:14.530Z","avatar_url":"https://github.com/donseba.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# go-translator\n\nOverview\n--\nThe Translator package is a Go module designed to facilitate easy and dynamic localization of applications. It provides a robust and flexible way to manage translations, including support for plural forms and customizable prefix handling for translation keys. This package utilizes the gotext library for managing PO files and integrates seamlessly with Go templates, making it an ideal solution for applications requiring multi-language support.\n\nFeatures\n--\n- **Dynamic Language Support**: Add new languages by parsing PO files.\n- **Template Integration**: Works with Go HTML templates, extracting translation keys directly from them.\n- **Pluralization Support**: Handles singular and plural forms for languages with complex plural rules.\n- **Contextual Translations**: Supports context-based translations for more accurate localization.\n- **Prefix Handling**: Customizable prefix handling in translation keys, allowing for organized and readable translation files.\n- **Missing Translation Detection**: Scans for and logs missing translations, simplifying the translation management process.\n\nInstallation\n--\nTo install the Translator package, use the following go get command:\n\n```bash\ngo get github.com/donseba/go-translator\n```\n\nUsage\n--\nInitializing the Translator\n\n```go\npackage main \n\nimport \"github.com/donseba/go-translator\"\n\nfunc main() {\n    translationsDir := \"path/to/translations\"\n    templateDir := \"path/to/templates\"\n\n    tr := translator.NewTranslator(translationsDir, templateDir)\n    tr.SetPrefixSeparator(\"__.\") // Set the prefix separator if different from the default\n\n    // load languages\n    tr.AddLanguage(\"en_US\")\n    tr.AddLanguage(\"nl_NL\")\n\n    // check for missing translations and add them to the pot file\n    err = app.Translation.CheckMissingTranslations(\"translations.pot\")\n    if err != nil {\n        log.Fatal(err)\n    }   \n\t\n    // add template functions\n    // this will add the tl, tn, ctl and ctn functions to the template\n    var yourTemplateFunctions = make(template.FuncMap) \n    for k, v := range tr.FuncMap() {\n        yourTemplateFunctions[k] = v\n    }\n```\n\nUsing the Translator in Templates\n--\nUse tl and ctl for translating singular texts and tn and ctn for plural forms.\n\n```html\n\u003c!-- Singular --\u003e\n\u003cp\u003e{{ tl .Loc \"Hello, World!\" }}\u003c/p\u003e\n\n\u003c!-- Plural --\u003e\n\u003cp\u003e{{ tn .Loc \"You have one message.\" \"You have %d messages.\" 5, 5 }}\u003c/p\u003e\n```\n\nLocalizer interface\n--\n\nThe Localizer interface is used to provide the translator with the current language. \nIt is used to determine the correct translation for the given key.\n\n```go\n\t//Localizer interface contains the methods that are needed for the translator\nLocalizer interface {\n   // GetLocale returns the locale of the localizer, ie. \"en_US\"\n   GetLocale() string\n}\n``` \n\n\nSetting a language to use\n--\n```go\ntr.SetLanguage(\"en_US\")\ntr.SetLanguage(\"nl_NL\")\n```\n\nSetting and possibly creating a New Language\n---------------------\n\nTo add or ensure a language file exists (and is loaded), use the `EnsureLanguage` method. This will create a new `.po` file with the correct header (including plural forms) if it does not exist, and then load it into the translator:\n\n```go\nerr := tr.EnsureLanguage(\"fr\") // creates fr.po if missing, with correct header\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n- The generated `.po` file will always include the recommended headers:\n  - `Content-Type: text/plain; charset=UTF-8`\n  - `Content-Transfer-Encoding: 8bit`\n  - `Plural-Forms` (auto-filled from plural rules)\n  - `Language` (set to the language code)\n\n- Calling `EnsureLanguage` multiple times is safe and will not overwrite existing files or translations.\n\nTesting and Idempotency\n-----------------------\n\n- The package includes tests to ensure that language files are created with the correct headers and that repeated calls to `EnsureLanguage` do not overwrite existing files.\n- Plural rules are generated from `plurals.json` and included in the codebase for accuracy and maintainability.\n\nUpdating Plural Rules\n---------------------\n\nIf you update `plurals.json`, regenerate the plural rules Go map by running:\n\n```sh\ngo run tools/generate_templates.go\n```\n\nThis will update `generated_plural_templates.go` with the latest plural forms and language codes.\n\nScanning for Missing Translations\n--\nTo check for missing translations in your templates:\n\n```go\nerr := tr.CheckMissingTranslations(\"messages.pot\")\nif err != nil {\nlog.Fatal(err)\n}\n```\nCustomizing Prefix Separator\n--\nYou can customize the prefix separator used in translation keys:\n\n```go\ntr.SetPrefixSeparator(\"__CUSTOM__\")\n```\nThe default prefix separator is `__.`\n\n\u003e **Note/Disclaimer:** While customizing the prefix separator is supported, it is generally recommended to use the CTL or CTN methods instead. These methods allow you to set translation context explicitly, which is more robust and flexible for handling similar keys in different contexts.\n\nRemoving Prefixes from Translations\n--\nThe package automatically handles the removal of prefixes from translations at runtime:\n\n```go\ntranslatedText := tr.Tl(localizer, \"prefix__.your_translation_key\") // output your_translation_key\n```\n\nTODO\n--\n- add caching functionality of the loaded translated keys.\n- add more unit tests\n- live reload translations when the file changes\n- fallback language\n\n\nContributing\n--\nContributions to the Translator package are welcome! Please submit a pull request or open an issue for any bugs, features, or improvements.\n\nLicense\n--\nThis package is licensed under MIT. Please see the LICENSE file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonseba%2Fgo-translator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonseba%2Fgo-translator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonseba%2Fgo-translator/lists"}