|
2 | 2 |
|
3 | 3 | Welcome to our i18n Guidelines! We appreciate your interest in translating our courses. |
4 | 4 |
|
5 | | -## Translations |
| 5 | +## Community Translations |
6 | 6 |
|
7 | | -At the moment, we have the courses in the following languages: |
| 7 | +At the moment, we are unable to offer translation maintenance. |
8 | 8 |
|
9 | | -### Intro to Open Source Course |
| 9 | +However, we know some contributors are willing to translate and help our courses to reach a broader audience. We value these contributions! ✨ |
10 | 10 |
|
11 | | -- [English](./intro-to-oss/README.md) |
12 | | -- [French](./intro-to-oss/translations/fr/README.md) |
13 | | -- Brazilian Portuguese — work in progress |
| 11 | +Please keep reading if you want to translate the [Open Source Education Path with OpenSauced](https://opensauced.pizza/learn/#/). |
14 | 12 |
|
15 | | -### Becoming a Maintainer Course |
| 13 | +## Why Translating Our Courses |
16 | 14 |
|
17 | | -- [English](./becoming-a-maintainer/README.md) |
| 15 | +Here are some benefits of translating our courses: |
18 | 16 |
|
19 | | -## How can I Contribute? |
| 17 | +- You will have the opportunity to learn to maintain a project and **become the maintainer** of the translation as it will live in your forked repository. |
| 18 | +- You can learn and experience collaborating with contributors, nurturing the translation community, and even assembling your own maintainers' team! |
| 19 | +- You will be able to learn how to deploy and host a static website on your own. |
| 20 | +- You can make the translation available as soon as possible for a broader audience. |
| 21 | +- You can update the translation faster by reviewing and merging in pull requests yourself as a maintainer. |
20 | 22 |
|
21 | | -There are two types of i18n contributions that we accept: |
| 23 | +> [!TIP] |
| 24 | +> It will be helpful taking our [Becoming a Maintainer](../docs/becoming-a-maintainer/README.md) course to equip you in maintaining your forked repository. |
22 | 25 |
|
23 | | -1. Translate our Intro to Open Source or Becoming a Maintainer course. |
24 | | -2. Review pull requests (PRs) and translations. |
| 26 | +## Getting Started |
25 | 27 |
|
26 | | -### Translate the Courses |
| 28 | +### 1. Forking the Repository |
27 | 29 |
|
28 | | -We have two types of translations: |
| 30 | +First, you must fork the [intro repository](https://github.com/open-sauced/intro). See the official GitHub docs for [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository). |
29 | 31 |
|
30 | | -#### 1. Official Translations |
| 32 | +### 2. Creating a Branch for the Translation |
31 | 33 |
|
32 | | -Official translations start as a post on our [GitHub Discussions](https://github.com/open-sauced/intro/discussions) board. If there is enough interest and volunteers, we can add the official translation as an option to view within our README. |
| 34 | +[Create a branch](https://www.shellhacks.com/git-create-new-branch-and-checkout/) where the translation changes will be merged. You can name this branch anything. For example: `jp-translations`. |
33 | 35 |
|
34 | | -#### 2. Community Translations |
| 36 | +> [!NOTE] |
| 37 | +> |
| 38 | +> - This will be the default branch of your translation and the one from which you deploy the translation. |
| 39 | +> - The `main` branch should be free from translations. |
35 | 40 |
|
36 | | -We can't always support the maintenance of translations. However, we know some contributors are willing to translate, and we value these contributions. For that reason, we have a [Community Translations](community-translations.md) section. |
| 41 | +### 3. Installing and Running the Project |
37 | 42 |
|
38 | | -If you're interested in translating our Intro to Open Source course, fork this repository and add the translation to your forked repository. Then, you can add a link to your translation in the `community-translations.md` file that you can find in the root directory. |
| 43 | +Read our [contributing guidelines](CONTRIBUTING.md#getting-started) to install and run the project locally. |
39 | 44 |
|
40 | | -We encourage you to add it to the [discussions board](https://github.com/open-sauced/intro/discussions) as well. We will consider moving it to an official translation if it becomes popular and has enough support. |
| 45 | +## Working with Translations |
41 | 46 |
|
42 | | -### Review Pull Requests (PRs) and Translations |
| 47 | +The translation process will take time, but don't let this stop you from making the ongoing translations available to the community. |
43 | 48 |
|
44 | | -If you are familiar with the translated language(s), you can help us review the translations and the PRs. Please head over to the "[Reviewer Process Guide](#reviewer-process-guide)" section for more information. |
| 49 | +What you need to know when working with translations: |
45 | 50 |
|
46 | | -## Adding Translations |
47 | | - |
48 | | -First, please read our [Contributing Guide](CONTRIBUTING.md) to setting up the project locally and for the technical instruction. Then, follow these steps to add the translations: |
49 | | - |
50 | | -1. **Identify target languages**. |
51 | | - |
52 | | - Determine which languages you want to add translations for. Make sure these languages are relevant to the project's user base. |
53 | | - |
54 | | -2. **Create translation files**. |
55 | | - |
56 | | - 1. Open the course directory inside the `docs` folder. |
57 | | - 2. Open the `translations` directory. |
58 | | - 3. Create a new subdirectory for each language you plan to support. Use language codes (e.g., "en" for English, "fr" for French, etc.) as directory names. |
59 | | - |
60 | | - ```markdown |
61 | | - . |
62 | | - └── translations/ |
63 | | - ├── en/ |
64 | | - ├── fr/ |
65 | | - └── es/ |
66 | | - ``` |
67 | | - |
68 | | -3. **Translate content**. |
69 | | - |
70 | | - - For each language directory, create translated versions of the documentation files. Typically, you translate Markdown files but consider other formats as needed. |
71 | | - - Maintain the same file names and structure as in the original documentation but with translated content. |
72 | | - |
73 | | -4. **Update links**. |
74 | | - |
75 | | - In the translated files, ensure that any internal links (e.g., links to other sections or pages within the documentation) are updated to point to the corresponding translated content. |
76 | | - |
77 | | -5. **Add a language selector**. |
78 | | - |
79 | | - Adding a language selector to the documentation allows users to switch between languages. You can do this by modifying the languages menu on the navigation bar: |
80 | | - |
81 | | - 1. Open the `docs` directory. |
82 | | - 2. Open the `_navbar.md` file in the course directory. |
83 | | - 3. In the "Languages" list, add a link to your translated language that includes the icon of the country's flag. Refer to the shortcode column in this [Country Flag emoji cheat sheet](https://github.com/ikatyang/emoji-cheat-sheet#country-flag) to help you. |
84 | | - |
85 | | - ```markdown |
86 | | - - [:jp: Japanese](/translations/jp/) |
87 | | - ``` |
88 | | - |
89 | | -6. **Testing and validation**. |
90 | | - |
91 | | - Test the translated documentation to ensure accuracy and readability. Ensure all links work correctly and the content is culturally appropriate. |
92 | | - |
93 | | -7. **Submit translations**. |
94 | | - |
95 | | - If you haven't already, submit your translations as a PR. Ensure you provide clear information about the languages you've translated and any specific details related to your contributions. |
96 | | - |
97 | | -8. **Collaborate and review**. |
| 51 | +- Maintain the original project's file names and structure, but replace all content with the translations. This will help preventing broken links. |
| 52 | +- Ensure there are no broken links and that all links navigate to the correct paths. |
| 53 | +- Maintain consistency in terminology and style throughout the translated documentation. |
| 54 | +- Keep translations up to date with changes in the original documentation. |
| 55 | +- When a course, a chapter, or a section hasn't been translated, you can add a note to inform the readers and direct them to [our website](https://opensauced.pizza/learn/#/). |
98 | 56 |
|
99 | | - Collaborate with other contributors and reviewers to ensure the quality of translations. Be open to feedback and suggestions for improvement. |
| 57 | +## Creating Contributing Guidelines for the Forked Repository |
100 | 58 |
|
101 | | -### Best Practices for Translations |
| 59 | +You have complete control of how you want contributors to contribute to your forked repo. Therefore, you want to create contributing guidelines for contributors to contribute to your forked repo. |
102 | 60 |
|
103 | | -- Maintain consistency in terminology and style throughout the translated documentation. |
104 | | -- Work with another contributor who speaks the language you're translating to. |
105 | | -- It helps to mention specific tools you use so developers who want to translate documentation can see how it's done. |
106 | | -- Keep translations up to date with changes in the original documentation. |
| 61 | +You can name this file anything _except_ `CONTRIBUTING.md`. For example: `contributing-jp.md`. |
107 | 62 |
|
108 | | -## Reviewer Process Guide |
| 63 | +Put the file in the `contributing` folder at the root. Then, add the link to it as the last list in the "[🤝 Contributing](../README.md#-contributing)" section on the root README as below: |
109 | 64 |
|
110 | | -When it comes to reviewing a translation PR, ask yourself the following questions: |
| 65 | +```markdown |
| 66 | +- For information on how to contribute to this translations repository, check out our [Translations Contributing Guidelines](LINK-TO-YOUR-FORKED-REPOSITORY-CONTRIBUTING-FILE). |
| 67 | +``` |
111 | 68 |
|
112 | | -- Does the current translation match the instructions in the English version? |
113 | | -- Are there links that could be localized and translated? (e.g., Wikipedia and MDN links) |
114 | | -- Is the translation correctly written following the translated language's norms and practices? |
| 69 | +## Adding Translation as a Community Translation |
115 | 70 |
|
116 | | -When you think a PR is ready to be merged after your suggestions were addressed (if any), approve it through GitHub's "Review Changes" button or leave an "LGTM!" in the comment section and tag the `@open-sauced/docs` maintainers. |
| 71 | +Once you are ready to share your translation, add it to the Community Translation list. |
117 | 72 |
|
118 | | -:::info |
119 | | -“LGTM” is an abbreviation of “Looks Good to Me” or “Let’s Get to Merging”, often used to approve pull requests. |
120 | | -::: |
| 73 | +Open the `community-translations.md` file located in the `contributing` folder on the root and list your translation. Read the instructions in the file to add it. |
0 commit comments