{"id":13404053,"url":"https://github.com/schmich/chrome-extension-localization","last_synced_at":"2025-10-26T11:52:06.210Z","repository":{"id":40050061,"uuid":"108484674","full_name":"schmich/chrome-extension-localization","owner":"schmich","description":"Organize and manage localization for your Chrome extension","archived":false,"fork":false,"pushed_at":"2019-10-20T00:18:57.000Z","size":2069,"stargazers_count":15,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-01T12:45:33.642Z","etag":null,"topics":["browser-extension","chrome","chrome-extension","i18n","internationalization","l10n","localization","translation","travis"],"latest_commit_sha":null,"homepage":"https://schmich.github.io/marinara-localization","language":"JavaScript","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/schmich.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}},"created_at":"2017-10-27T01:34:16.000Z","updated_at":"2024-07-29T21:33:57.000Z","dependencies_parsed_at":"2022-07-27T14:19:58.414Z","dependency_job_id":null,"html_url":"https://github.com/schmich/chrome-extension-localization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmich%2Fchrome-extension-localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmich%2Fchrome-extension-localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmich%2Fchrome-extension-localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmich%2Fchrome-extension-localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schmich","download_url":"https://codeload.github.com/schmich/chrome-extension-localization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238614544,"owners_count":19501478,"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":["browser-extension","chrome","chrome-extension","i18n","internationalization","l10n","localization","translation","travis"],"created_at":"2024-07-30T19:01:38.291Z","updated_at":"2025-10-26T11:52:06.131Z","avatar_url":"https://github.com/schmich.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Chrome Extension Localization\n\nChrome Extension Localization helps you organize and manage the process of localizing your Chrome extension\nvia [Travis CI](https://travis-ci.org/) automatic deployments and [GitHub Pages](https://pages.github.com/) hosting.\n\nTry the [live example site](https://schmich.github.io/marinara-localization), read the [translation guide](#translation-guide), or [setup your extension for localization](#setup-guide).\n\n## Overview\n\nChanges to your localized `messages.json` files trigger a Travis CI deployment to an auxiliary GitHub repo you\ncontrol. That repo is hosted with GitHub Pages and serves up message localization information. Translators\ncan use the site to add and update translations. To complete the cycle, the site helps translators create\nGitHub pull requests for their changes.\n\n### Workflow\n\n1. Translator makes a change to a localization file, e.g. `_locales/es/messages.json`\n2. Translator commits changes and pushes them to your extension repo on GitHub\n3. Travis CI clones your repo and creates a localization summary file called `locales.json`\n4. Travis CI commits and pushes `locales.json` to your extension localization repo on GitHub\n5. GitHub serves your extension localization repo as a GitHub Pages website\n6. Translators use your localization website to add and update translations\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/diagram.png\"/\u003e\u003c/p\u003e\n\n## Setup Guide\n\nThis guide assumes your Chrome extension source is hosted on GitHub and can be integrated with [Travis CI](https://travis-ci.org/). The following steps will get you started with using Chrome Extension Localization to manage your localization efforts.\n\nThis tool was created to help localize the [Marinara](https://github.com/schmich/marinara) Chrome extension.\nThe following walkthrough will use `marinara` as the example project name and `schmich` as the example user name.\n\n1. [Create a new GitHub repo](https://github.com/new) called `marinara-localization`. It will serve as the GitHub Pages host for the localization website:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-create-repo.png\"/\u003e\u003c/p\u003e\n\n2. Clone `marinara-localization`:\n\n```\n/src$ git clone git@github.com:schmich/marinara-localization \u0026\u0026 cd marinara-localization\n```\n\n3. Add `chrome-extension-localization` as a submodule:\n\n```\n/src/marinara-localization$ git submodule add https://github.com/schmich/chrome-extension-localization\n```\n\n4. Create a symbolic link to `index.html` for GitHub Pages:\n\n```\n/src/marinara-localization$ ln -s chrome-extension-localization/web/index.html .\n```\n\n5. Commit and push your changes:\n\n```\n/src/marinara-localization$ git commit -am 'Initial commit.' \u0026\u0026 git push\n```\n\n6. Enable GitHub Pages on the master branch for `marinara-localization` at https://github.com/schmich/marinara-localization/settings:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-enable-pages.png\"/\u003e\u003c/p\u003e\n\n7. In your extension source (`marinara`) create a folder called `deploy`:\n\n```\n/src/marinara$ mkdir deploy \u0026\u0026 cd deploy\n```\n\n8. Add `chrome-extension-localization` as a submodule:\n\n```\n/src/marinara/deploy$ git submodule add https://github.com/schmich/chrome-extension-localization\n```\n\n9. Create a dedicated deployment key for deploying from Travis to the `marinara-localization` repo:\n\n```\n/src/marinara/deploy$ ssh-keygen -t rsa -b 4096 -C \"Travis CI Deployment Key\" -f deploy_key\nGenerating public/private rsa key pair.\nEnter passphrase (empty for no passphrase): \nEnter same passphrase again: \nYour identification has been saved in deploy_key.\nYour public key has been saved in deploy_key.pub.\nThe key fingerprint is:\nSHA256:nY5jLr0JFgOZfBp1N/hLPiPj7jIT9K4vGYwT/PubevI Travis CI Deployment Key\n...\n```\n\n10. Add `deploy_key` to your `.gitignore`. It's a private key that should *never* be committed to your repo:\n\n```\n/src/marinara/deploy$ echo deploy_key \u003e\u003e ../.gitignore\n```\n\n11. Add the contents of `deploy_key.pub` as a deployment key for `marinara-localization` at https://github.com/schmich/marinara-localization/settings/keys *(example key shown)*:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-add-deploy-key.png\"/\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-deploy-keys.png\"/\u003e\u003c/p\u003e\n\n12. Install the Travis command-line tool:\n\n```\n/src/marinara/deploy$ gem install travis\nFetching: travis-1.8.8.gem (100%)\nSuccessfully installed travis-1.8.8\nParsing documentation for travis-1.8.8\nInstalling ri documentation for travis-1.8.8\nDone installing documentation for travis after 2 seconds\n1 gem installed\n```\n\n13. Enable Travis builds for `marinara`:\n\n```\n/src/marinara/deploy$ travis enable\nschmich/marinara: enabled :)\n```\n\n14. Copy the Travis configuration template into `marinara`:\n\n```\n/src/marinara/deploy$ (cd .. \u0026\u0026 curl -LO \"https://raw.githubusercontent.com/schmich/chrome-extension-localization/master/deploy/.travis.yml\")\n```\n\n15. Edit `.travis.yml` and change `COMMIT_AUTHOR_NAME`, `COMMIT_AUTHOR_EMAIL`, and `LOCALES_PATH`. `LOCALES_PATH` is the\nrelative path from your repo root to your `_locales` folder where your translations are stored:\n\n```yaml\nscript: true\nenv:\n  global:\n  - COMMIT_AUTHOR_NAME: \"'Chris Schmich'\"\n  - COMMIT_AUTHOR_EMAIL: schmch@gmail.com\n  - LOCALES_PATH: src/_locales\n...\n```\n\n16. Encrypt the deployment key with Travis. The tool will create an encrypted version of the deployment private key, `deploy_key.enc`:\n\n```\n/src/marinara/deploy$ travis encrypt-file deploy_key --add\nencrypting deploy_key for schmich/marinara\nstoring result as deploy_key.enc\nstoring secure env variables for decryption\n\nMake sure to add deploy_key.enc to the git repository.\nMake sure not to add deploy_key to the git repository.\nCommit all changes to your .travis.yml.\n```\n\n17. Verify Travis settings at https://travis-ci.org/schmich/marinara/settings. Ensure the `encrypted_*_iv` and `encrypted_*_key` environment variables are present:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/travis-settings.png\"/\u003e\u003c/p\u003e\n\n18. Add the deployment files to `marinara`:\n\n```\n/src/marinara/deploy$ git add chrome-extension-localizatoin deploy_key.{enc,pub} ../.{travis.yml,gitignore}\n```\n\n19. Commit and push the new files:\n\n```\n/src/marinara/deploy$ git commit \u0026\u0026 git push\n```\n\n20. Your push will trigger Travis to build and deploy `marinara`. Monitor progress at https://travis-ci.org/schmich/marinara:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/travis-build.png\"/\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/travis-log.png\"/\u003e\u003c/p\u003e\n\n21. Travis' deployment step will generate `locales.json` which will be committed and pushed to the `marinara-localization` repo:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/localization-repo.png\"/\u003e\u003c/p\u003e\n\n22. GitHub will publish the localization site to https://schmich.github.io/marinara-localization. This site can be used to manage localization for your extension:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-list.png\"/\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-editor.png\"/\u003e\u003c/p\u003e\n\n## Updating Submodules\n\nBoth your `extension` and `extension-localization` projects link to `chrome-extension-localization` as a git\nsubmodule. You can periodically update your submodule references to get the latest features and bug fixes.\n\nWhen updating, ensure that you reference the same submodule version (commit hash) in both projects:\n\n```\n/src/marinara$ git submodule update --remote deploy/chrome-extension-localization\nSubmodule path 'deploy/chrome-extension-localization': checked out 'dab0105375efef675ee06b943e40d5fcbfc704bd'\n```\n\n```\n/src/marinara-localization$ git submodule update --remote chrome-extension-localization\nSubmodule path 'chrome-extension-localization': checked out 'dab0105375efef675ee06b943e40d5fcbfc704bd' \n```\n\n## Translation Guide\n\nYou need a [GitHub account](https://github.com/join) to create pull requests for your translations.\n\n1. Open the project localization website, e.g. https://schmich.github.io/marinara-localization/\n\n2. Select the locale to update or create. If a locale doesn't exist, that means there is no corresponding\n`messages.json` file for it yet. You can be the first to translate for it:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-select.png\"/\u003e\u003c/p\u003e\n\n3. On the translation page, you will see a table of messages used in the extension. As you add and update \ntranslations, the app will save your work locally in-browser. Each message has a few properties:\n\n    - *Message ID* is the programmatic ID used in the extension\n    - *en: English* is the source English message\n    - *State* indicates any issues with the message (see below)\n    - *es: Spanish* is the editable translation\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-add-translation.png\"/\u003e\u003c/p\u003e\n\n4. Messages can contain placeholders which the extension determines at runtime. For example, the message `Hello, $name$!` has `$name$` as a placeholder. Use the placeholder in your translation, but do not translate the placeholder itself. In this case, the Spanish translation would be `¡Hola, $name$!`.\n\n5. Message states indicate potential translation issues. You can show or hide messages based on these states:\n\n    - *Normal*: Messages without any issues\n    - *Missing*: Messages that have not been translated; they need translating\n    - *Outdated*: Messages with English counterparts that changed since translation; the translation might need updating to reflect the English changes\n    - *Identical*: Messages that are identical to their English counterparts; they might need translating\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-message-filters.png\"/\u003e\u003c/p\u003e\n\n6. Once you have finished adding and updating translations, export your work to a JSON-formatted\n`messages.json` file. This file contains all translations for the locale and will be bundled with the extension.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/locale-export.png\"/\u003e\u003c/p\u003e\n\n7. Click the GitHub link to start the pull request process to contribute your translations. If you haven't\nforked the extension repository already, you will be prompted to do so:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-must-fork.png\"/\u003e\u003c/p\u003e\n\n8. Paste from your clipboard or copy-paste the contents of the downloaded `messages.json` file and propose your changes:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-edit-file.png\"/\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-propose-change.png\"/\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-compare-changes.png\"/\u003e\u003c/p\u003e\n\n9. That's it! Wait for the maintainer to merge your pull request:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"assets/github-open-pull-requests.png\"/\u003e\u003c/p\u003e\n\n## License\n\nCopyright \u0026copy; 2017 Chris Schmich  \nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmich%2Fchrome-extension-localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschmich%2Fchrome-extension-localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmich%2Fchrome-extension-localization/lists"}