{"id":19852523,"url":"https://github.com/thesoftwarehouse/babelsheet2","last_synced_at":"2025-05-02T00:31:21.054Z","repository":{"id":88617741,"uuid":"440644984","full_name":"TheSoftwareHouse/babelsheet2","owner":"TheSoftwareHouse","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-28T07:57:21.000Z","size":1027,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-06T20:22:50.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/TheSoftwareHouse.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":"2021-12-21T20:41:09.000Z","updated_at":"2025-03-28T07:57:25.000Z","dependencies_parsed_at":"2023-11-16T08:29:41.689Z","dependency_job_id":"e699885a-3923-4150-a0c3-6616c8f40e24","html_url":"https://github.com/TheSoftwareHouse/babelsheet2","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/TheSoftwareHouse%2Fbabelsheet2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSoftwareHouse%2Fbabelsheet2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSoftwareHouse%2Fbabelsheet2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheSoftwareHouse%2Fbabelsheet2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheSoftwareHouse","download_url":"https://codeload.github.com/TheSoftwareHouse/babelsheet2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251966431,"owners_count":21672666,"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":[],"created_at":"2024-11-12T14:03:16.388Z","updated_at":"2025-05-02T00:31:16.037Z","avatar_url":"https://github.com/TheSoftwareHouse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Babelsheet2\n\n🇬🇧 🇪🇸 🇫🇷 🇩🇪 🇵🇱 🇨🇳\n\nBabelsheet2 is a tool that addresses one of the biggest [i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization) issue. Namely, it provides frictionless way\nof cooperation between language translators and developers.\n\n## 💡 How it works?\n\nBabelsheet2 uses Google Spreadsheets for translations single source of truth because it is an acceptable tool \nfor non-technical people (Excel-like tools are pretty common and have low entry threshold). The spreadsheet\nhas some structure where part of it is filled by the developer and the other part is to be completed by\nthe language translator.\n\nThe structure of the spreadsheet has been explained well [in the primary Babelsheet project](https://github.com/TheSoftwareHouse/babelsheet/blob/master/README.md#markup) that this one is based on.\n\nThen, to include these translations in the app, Babelsheet2 provides some API\nthat is able to fetch, parse and write translations defined in the spreadsheet \ninto your file system in the format you want.\n\n## 🤔 Why \"2\"?\n\nThis project is based on [babelsheet](https://github.com/TheSoftwareHouse/babelsheet) and [babelsheet-js](https://github.com/TheSoftwareHouse/babelsheet-js) projects idea, \nwhich is a very cool. However, the implementation of that idea\ntaught us some lessons that some things can be done better. Hence, we release version 2 with a bit \ndifferent approach that should solve some problems that were hard to be solved in the primary version.\n\n## 🧰 Prerequisites\n\nBefore you begin the setup of the Babelsheet2, you need to create a Google Service Account, so\nBabelsheet2 will be able to perform some actions on Google Services in your behalf.\n\nTo do that, go to your [Google Cloud Platform's Dashboard](https://console.cloud.google.com/) first. If you are using it for \nthe first time, you may have to create your first Project there to be able to perform any actions. \nSo, select some existing project in which scope you would like to store the translations, or create a new one.\n\n![Google Cloud Platform navigation top bar](docs/images/google-dashboard-navbar.png)\n\nThen [create service account](https://console.cloud.google.com/iam-admin/serviceaccounts/create) in that project's scope.\nYou can name it however you want. In terms of the account access setup, you don't need to add any role for this account so\njust click \"Continue\" button on this step. Also, the other \"Grant users access to this service account\" step is optional too.\n\n![Create service account page](docs/images/create-service-account.png)\n\nWhen you create the service account, open its details manager by clicking its e-mail from the list.\nThen generate new JSON-format credentials like follows:\n\n1. Open \"KEYS\" tab\n2. Click \"ADD KEY\" drop down ![Service \"Keys\" tab](docs/images/service-keys.png)\n3. Select \"Create new key\"\n4. Make sure that \"JSON\" format is selected in the dialog that popped up ![Create private key dialog](docs/images/create-service-key.png)\n5. Click \"CREATE\"\n6. Save the downloaded file in your project's root directory and name it `.credentials.json`\n7. Although the created service account does not have too much permissions, \n   it's recommended that you add this file to `.gitignore` in your project and distribute it\n   among the developers that are involved in your project in other way.\n   \n\n## 🔧 Installation\n\n### npx way\n\nIf you have `npx` installed, you can run the following command to initialize the Babelsheet2\nin your project directory:\n\n```bash\nnpx babelsheet2 init\n```\n\n### Global way\n\nAlternatively, if you don't have `npx` you can install Babelsheet2 CLI tool globally:\n\n```bash\nnpm i -G babelsheet2\n```\n\n...and then you should be able to execute following command whenever you want to set up Babelsheet2 \nfor some of your projects:\n\n```bash\nbabelsheet2 init\n```\n\n### Next steps\n\nThe Babelsheet2 CLI leads you by hand during init process. It will share the spreadsheet file (on the e-mail and as a link in the console output) with you\nwhere you can fill first translation keys. The next thing that you will probably need is\nto share that spreadsheet with language translators, and the developers that work on the same project.\nAlso, as mentioned in the \"Prerequisites\" section above, you may need to share the `.credentials.json` file\nwith the developers so they are able to run the translation fetching script.\n\nIf everything has been set up correctly, you should be able to run the translation fetching script for instance like this\n(it depends on the configuration):\n\n```bash\nnpm run translations\n```\n\n...and this will update the translation files each time you run it basing on the Google Spreadsheet file content.\n\n### Comment on further automation\n\nYou may want to execute this script during the build process or for instance on some CI. This is doable,\nhowever we recommend you to execute the translations fetching script manually to be able to perform last check\nof translations if they are ok before committing them into the repository. This way you may avoid a risk of \ndeployment of some mistake straight ahead into production environment. Remember, the mistakes happen, especially\nwhen non-technical people are involved in the process. They may for instance edit the wrong cell \nand break the translation files structure unintentionally by doing so.\n\n## 💎 Core values\n\nThis project has some goals that we would like to keep in mind during the development process.\nThey are listed below.\n\n### 🔗 Reduced dependencies\n\nToo much dependencies may result not only a big `node_modules` directory,\nbut also may affect negatively on maintainability of the project. \nThe more dependencies you have, the higher the probability of problems with dependency updates.\n\nHence, we don't want this tool to handle every file format on the world out-of-the-box.\nInstead, every package should have single responsibility and use only the dependencies\nthat are crucial to make it work.\n\n### 👨‍💻 Developer Experience\n\nEverything that is a monotonous task and could be automated,\nshould be automated. Hence, there is a CLI command\nthat enables a developer to set up their project for translations\neasily by asking a couple of questions. It is able to generate the\nspreadsheet, share it with you and registers the \ntranslation fetching script in your project.\n\n### 🔧 Customization\n\nNo matter how much use cases your solution covers, there will be always\n that project that your clever tool mechanisms do not fit at all to. \nThat's the reason why Babelsheet2 shares an API that enables you to write\ncustom script for translation files generation.\n\n### ♟️ Reasonable defaults\n\nToo much customizability may result with overwhelming and time consuming\nprocess of setup. Hence, for beginner users there should be a simpler way\nwhere they don't have to configure every tiny aspect. In Babelsheet2\nthere are default settings predefined that enable to start\nworking with the tool in a fast and straightforward manner.\n\n### 🥳 Emojis\n\nThe days when console output had to be monotonous text are long gone.\nIt can be decorated a bit with emojis to improve readability and fun 😉","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesoftwarehouse%2Fbabelsheet2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesoftwarehouse%2Fbabelsheet2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesoftwarehouse%2Fbabelsheet2/lists"}