Application text localization files for Scribe apps

Scribe-i18n is the home of the localization files that are included in each Scribe application. Scribe uses Weblate for localization! Head over to weblate.org/projects/scribe/scribe-i18n to localize the applications. Changes in this directory will be merged into other Scribe applications via this repo being a Git subtree.

[!NOTE]\ The contributing section has information for those interested.

Scribe apps are available on iOS, Android (planned) and Desktop (planned). For the data formatting processes see Scribe-Data and for our data download API see Scribe-Server.

Check out Scribe's architecture diagrams for an overview of the organization including our applications, services and processes. It depicts the projects that Scribe is developing as well as the relationships between them and the external systems with which they interact.

Contents

• Localization Coverage
• Contributing
• Community

Localization Coverage ⇧

Contributing ⇧

Thank you for your interest in contributing to Scribe-i18n! We look forward to welcoming you to the community and working with you to build tools for language learners to communicate effectively :) The following are some suggested steps for people interested in joining our community.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open-source project. In return, and in accordance with this project's code of conduct, other contributors will reciprocate that respect in addressing your issue or assessing changes and features.

If you have questions or would like to communicate with the team, please join us in our public Matrix chat rooms. Scribe would suggest that you use the Element client. We'd be happy to hear from you!

Issues ⇧

The issue tracker for Scribe-i18n is the preferred channel to let the team know if there are problems with localizations or to ask to work on new ones. Those interested in helping can check the -next release- and -priority- labels in the issues for those that are most important, as well as those marked good first issue that are tailored for first time contributors. Generally issues in this repository will be marked with the localization label.

Localizing Via Weblate ⇧

Weblate localization is as easy as making an account and jumping into the Scribe-i18n project!

1. First register at Weblate (you can also authenticate with GitHub or other accounts)

   • We suggest that you do link your GitHub account so you get credit for the localization commits!

2. Navigate to the Scribe-i18n project at weblate.org/projects/scribe/scribe-i18n

3. Click on a language you want to start translating

4. You can browse the available strings or start translating directly

   • When translating a word, be sure to check the glossary context if you're not sure what the string's use is

   • You can also make use of Automatic suggestions to see machine translations if you need help

5. Hit Save and continue when you're ready to move to the next string

6. Maintainers will open up pull requests from Weblate to the Scribe-i18n repo to bring in the new strings

   • Changes are also automatically sent every 24 hours

7. Scribe-i18n directories that are Git subtrees in other Scribe application repos are then synched. For each project using Scribe-i18n:

   • Navigate to the root of the Scribe project's repo

   • To load into the project the latest Scribe-i18n updates, run the following - where subtree-directory is the directory within the repo structure with the Scribe-i18n subtree:

     git subtree pull --prefix <subtree-directory> git@github.com:scribe-org/Scribe-i18n.git main --squash

   • From the above command, two commits are then auto-generated. Finally, create the PR to the given project to bring in the Scribe-i18n updates.

Thanks so much for your interest in supporting Scribe's localization!

Adding Source Strings ⇧

The base language for all Scribe applications is US English. If you'd like to edit the en-US.json file, please fork the repo, clone your fork, and configure the remotes:

[!NOTE]

Consider using SSH

Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow. To run git commands with SSH, remember then to substitute the HTTPS URL, `https://github.com/...`, with the SSH one, `git@github.com:...`. - e.g. Cloning now becomes `git clone git@github.com:/Scribe-i18n.git` GitHub also has their documentation on how to [Generate a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) 🔑

# Clone your fork of the repo into the current directory.
git clone https://github.com/<your-username>/Scribe-i18n.git
# Navigate to the newly cloned directory.
cd Scribe-i18n
# Assign the original repo to a remote called "upstream".
git remote add upstream https://github.com/scribe-org/Scribe-i18n.git

• Now, if you run git remote -v you should see two remote repositories named:
  • origin (forked repository)
  • upstream (Scribe-i18n repository)

If all looks good, then you're ready to start adding localizable key-string pairs via pull requests!

File Conversion

The files in the Scribe-i18n/scripts directory can be used to convert base localization JSON files into the filetypes that are needed for an application as well as the same in reverse. JSON files are automatically converted to their target files for Scribe applications after commits to the main branch, and their opposites can be used to update the JSON files when strings are first changed in the applications.

Adding Scribe-i18n to Projects ⇧

To use Scribe-i18n within another repository, run the following command from the root directory of the project to add Scribe-i18n as a subtree:

git subtree add --prefix <subtree-directory> git@github.com:scribe-org/Scribe-i18n.git main --squash

In the command, the value for subtree-directory is a directory within the repo structure of the project. Which directory to use will be dependent on the stack of the project and how i18n files will be consumed. Typically, this is the path for a directory named i18n that will be created somewhere in the repo structure upon command execution. Refer to documentation of the tool that will consume the i18n files to determine what it should be.

Pull Requests ⇧

Good pull requests are the foundation of our community making Scribe-i18n. They should remain focused in scope and avoid containing unrelated commits. Note that all contributions to this project will be made under the specified license.

When making a contribution, adhering to the GitHub flow process is the best way to get your work merged:

1. If you cloned a while ago, get the latest changes from upstream:

   git checkout <dev-branch>
   git pull upstream <dev-branch>

2. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:

   git checkout -b <topic-branch-name>

3. Commit your changes in logical chunks, and please try to adhere to Conventional Commits.

[!NOTE] The following are tools and methods to help you write good commit messages ✨

• commitlint helps write Conventional Commits
• Git's interactive rebase cleans up commits

4. Locally merge (or rebase) the upstream development branch into your topic branch:

   git pull --rebase upstream <dev-branch>

5. Push your topic branch up to your fork:

   git push origin <topic-branch-name>

6. Open a Pull Request with a clear title and description.

Thank you in advance for your contributions!

Community ⇧

Joining In ⇧

After your first few pull requests organization members would be happy to discuss granting you further rights as a contributor, with a maintainer role then being possible after continued interest in the project. Scribe seeks to be an inclusive and supportive organization. We'd love to have you on the team!

Road Map ⇧

The Scribe road map can be followed in the organization's project board where we list the most important issues along with their priority, status and an indication of which sub projects they're included in (if applicable).

[!NOTE]\ Consider joining our bi-weekly developer syncs!

Powered By ⇧

Contributors

Many thanks to all the Scribe-i18n contributors! 🚀