opensource/freeCodeCamp
3
0
Fork 0
mirror of https://github.com/freeCodeCamp/freeCodeCamp.git synced 2026-09-24 23:01:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): update docs of enabling new language (#50921)

Browse Source
This commit is contained in:
sidemt
2023-07-10 16:38:40 +05:30
committed by GitHub
parent fb1228546e
commit 05a505bf2f
1 changed files with 83 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/how-to-enable-new-languages.md
+83 -21
View File
@@ -1,14 +1,36 @@
# Deploying New Languages on `/learn`
Before you can release a new language, you will need to allow the languages to download from Crowdin.
To enable a new language on `/learn` (curriculum), you need to complete the following steps:
- Complete translating and approving the first 3 certifications on Crowdin. (New Responsive Web Design, JavaScript Algorithms and Data Structures, and Front End Development Libraries)
- Complete translating and approving all strings in Learn UI project on Crowdin.
- Update Crowdin settings to add a custom language code for the new language.
- Open the 1st PR to configure GitHub Actions. You need to update 2 files:
- `crowdin-download.client-ui.yml`
- `crowdin-download.curriculum.yml`
- Open the 2nd PR to add other configurations. You need to update/add the following files:
- Update `i18n.ts`
- Update `superblocks.ts`
- Update `algolia-locale-setup.ts`
- Add `links.json`
- Add `meta-tags.json`
- Add `motivation.json`
- Ask infrastructure team to spin up the VM for the new language.
- Once the VM is ready, open the 3rd PR to show the new language in the navigation menu.
We will explain each step in the following sections.
## Updating Crowdin Settings
In the `Curriculum` and `Learn UI` projects, you will need to select `Project Settings` from the sidebar. Then scroll down to `Language Mapping`, where you will see an option to add custom language codes. Add a new entry for the language you are releasing, selecting `language` as the `Placeholder` value, and entering a URL-friendly lower-case spelling of your language's name for the `Custom code`. If you aren't sure what to use, reach out in our contributor chat and we will assist you.
Before you can release a new language, you will need to allow the languages to download from Crowdin. To configure that, you need to add a custom language code for your language.
## Updating Workflows
In the `Curriculum` and `Learn UI` projects on Crowdin, you will need to select `Settings` > `Languages` from the sidebar. Then scroll down to `Language Mapping`, where you will see an option to add custom language codes. Add a new entry for the language you are releasing, selecting `language` as the `Placeholder` value, and entering a URL-friendly lower-case spelling of your language's name for the `Custom code`. If you aren't sure what to use, or you don't have an admin role and can't see the settings, reach out in our contributor chat and we will assist you.
You will need to add a step to the `crowdin-download.client-ui.yml` and `crowdin-download.curriculum.yml`. The step for these will be the same. For example, if you want to enable Dothraki downloads:
## Updating Workflows for GitHub Actions
Then you need to configure the syncing between Crowdin and GitHub.
You will need to add a step to the [`crowdin-download.client-ui.yml`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/.github/workflows/crowdin-download.client-ui.yml) and [`crowdin-download.curriculum.yml`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/.github/workflows/crowdin-download.curriculum.yml). The step for these will be the same. For example, if you want to enable Dothraki downloads:
```yml
##### Download Dothraki #####
@@ -50,14 +72,14 @@ Note that the `download_language` key needs to be set to the language code displ
There are a few steps to take in order to allow the codebase to build in your desired language.
First, visit the `config/i18n.ts` file to add the language to the list of available languages and configure the values. There are several objects here.
First, visit the [`config/i18n.ts`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/config/i18n.ts) file to add the language to the list of available languages and configure the values. There are several objects here.
- `Languages`: Add the new language to `Languages` enum, similar to the others. The string value here will be used in the `.env` file to set a build language later.
- `availableLangs`: Add the new property from the `Languages` enum to both the `client` and `curriculum` arrays.
- `i18nextCodes`: These are the ISO language codes for each language. You will need to add the appropriate ISO code for the language you are enabling. These do need to be unique for each language.
- `LangNames`: These are the display names for the language selector in the navigation menu.
- `LangCodes`: These are the language codes used for formatting dates and numbers. These should be Unicode CLDR codes instead of ISO codes.
- `hiddenLangs`: These languages will not be displayed in the navigation menu. This is used for languages that are not yet ready for release.
- `hiddenLangs`: These languages will not be displayed in the navigation menu. This is used for languages that are not yet ready for release. Include your language in this array in the first PR and ask staff team to prepare the VM instance for your language. When the VM is ready, make another PR to remove it from the array.
- `rtlLangs`: These are languages that read from right to left.
As an example, if you wanted to enable Dothraki as a language, your `i18n.ts` objects should look like this:
@@ -118,7 +140,7 @@ export const rtlLangs = [''];
```
> [!NOTE]
> When a language has been set up in the deployment pipeline AND has a public `/news` instance live, it can be removed from the `hiddenLangs` array and be made available to the public.
> When a language has been set up in the deployment pipeline AND has a public `/learn` instance live, it can be removed from the `hiddenLangs` array and be made available to the public.
### Set Translated SuperBlocks
@@ -151,7 +173,7 @@ See the `SuperBlocks` enum at the beginning of the same file for the full list o
### Configure Search
Next, open the `client/src/utils/algolia-locale-setup.ts` file. This data is used for the search bar that loads `/news` articles. While it is unlikely that you are going to test this functionality, missing the data for your language can lead to errors when attempting to build the codebase locally.
Next, open the [`client/src/utils/algolia-locale-setup.ts`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/client/src/utils/algolia-locale-setup.ts) file. This data is used for the search bar that loads `/news` articles. While it is unlikely that you are going to test this functionality, missing the data for your language can lead to errors when attempting to build the codebase locally.
Add an object for your language to the `algoliaIndices` object. You should use the the same values as the `english` object for local testing, replacing the `english` key with your language's `availableLangs` value.
@@ -182,12 +204,52 @@ const algoliaIndices = {
name: 'news',
searchPage: 'https://www.freecodecamp.org/news/search/'
}
// If we already have /news in the target language up and running, you can update the values like this:
// dothraki: {
// name: 'news-mis',
// searchPage: 'https://www.freecodecamp.org/dothraki/news/search/'
// }
};
```
### Client UI
You will need to take an additional step to handle the client UI translations.
The Crowdin workflows will automatically pull down _some_ of the UI translations, but there are a couple of files that need to be moved manually.
You will want to copy the following files from [`/client/i18n/locales/english`](https://github.com/freeCodeCamp/freeCodeCamp/tree/main/client/i18n/locales/english) to `/client/i18n/locales/<your-language>`, and apply translations as needed:
- `links.json`
- `meta-tags.json`
- `motivation.json`
You don't have to have everything in these 3 files translated at first. It's possible to translate only the relevant parts and make adjustments later.
#### `links.json`
You can replace any URLs that you have corresponding pages ready in your language.
For example, if you have the publication in your language, you can replace the URL for `"news"`. If you want to translate articles listed in the footer links, see [How to Translate Articles in the Footer Links](language-lead-handbook.md#how-to-translate-articles-in-the-footer-links).
#### `meta-tags.json`
This file contains metadata for the web page of `/learn` in your language. You can translate the values for `"title"`, `"description"`, and `"social-description"`. The value for `"youre-unsubscribed"` is used when someone unsubscribes from Quincy's weekly email.
Also, you can translate or add relevant keywords in your language to the `"keywords"` array.
#### `motivation.json`
This file contains the compliments that will be displayed to campers when they complete a challenge, and motivational quotes that are displayed on the top page of `/learn`.
You can translate them, or even replace them with relevant compliments/quotes of your choice in your language.
### Enabling Localized Videos
For the video challenges, you need to change a few things. First, add the new locale to the GraphQL query in the `client/src/templates/Challenges/video/Show.tsx` file. For example, adding Dothraki to the query:
This section is applicable only if you have localized videos in the challenges. Otherwise, you can skip this section.
For the video challenges, you need to change a few things. First, add the new locale to the GraphQL query in the [`client/src/templates/Challenges/video/Show.tsx`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/client/src/templates/Challenges/video/show.tsx) file. For example, adding Dothraki to the query:
```tsx
query VideoChallenge($slug: String!) {
@@ -239,18 +301,6 @@ videoLocaleIds: Joi.when('challengeType', {
}),
```
## Client UI
You will need to take an additional step to handle the client UI translations.
The Crowdin workflows will automatically pull down _some_ of the UI translations, but there are a couple of files that need to be moved manually.
You will want to copy the following files from `/client/i18n/locales/english` to `/client/i18n/locales/<your-language>`, and apply translations as needed:
- `links.json`
- `meta-tags.json`
- `motivation.json`
## Testing Translations Locally
If you would like to test translations locally, before adding them to our main repository - skip the Crowdin workflow changes. Follow the steps for enabling a language, then download the translations from Crowdin and load them into your local code.
@@ -269,6 +319,18 @@ Once these are in place, you should be able to run `pnpm run develop` to view yo
> [!ATTENTION]
> While you may perform translations locally for the purpose of testing, we remind everyone that translations should _not_ be submitted through GitHub and should only be done through Crowdin. Be sure to reset your local codebase after you are done testing.
## Show the language in the navigation menu
When your prior PR is merged and the VM for your language is ready, make another PR to show your language in the navigation menu.
In [`config/i18n.ts`](https://github.com/freeCodeCamp/freeCodeCamp/blob/main/config/i18n.ts) file, you have included your language in `hiddenLangs` array in the prior PR. Remove it from the array now.
```js
export const hiddenLangs = []; // Remove your language from the array
```
When this PR is merged and gets deployed, the curriculum in your language will be live.
# Deploying New Languages on `/news`
To deploy News for a new language, you'll need to create two PRs. One PR will be to the [CDN repo](https://github.com/freeCodeCamp/cdn), and the other will be to the [News repo](https://github.com/freeCodeCamp/news).