docs(docs, i18n): add instruction for internal links (#46509)

* docs: add instruction for internal links

* docs: add examples in HTML

docs/_sidebar.md

@@ -15,7 +15,7 @@
   - [Work on localized client web app](how-to-work-on-localized-client-webapp.md)
   - [Work on Cypress tests](how-to-add-cypress-tests.md)
   - [Work on video challenges](how-to-help-with-video-challenges.md)
-  - [Work on the docs theme](how-to-work-on-the-docs-theme.md)
+  - [Work on documentation](how-to-work-on-the-docs-theme.md)
   - [Work on the component library](how-to-work-on-the-component-library.md)
 - **Additional Guides**
   - [Test translations locally](how-to-test-translations-locally.md)

docs/how-to-translate-files.md

@@ -122,6 +122,42 @@ Translating our contributing documentation is a similar flow to translating our
 > [!NOTE]
 > Our contributing documentation is powered by `docsify`, and we have special parsing for message boxes like this one. If you see strings that start with `[!NOTE]`, `[!WARNING]`, or `[!TIP]`, these words should NOT be translated.
 
+### How to translate documentation with internal links
+
+When you work on translating contributing documentation, watch out for internal links targeting a different section of the documentation.
+
+Make sure to replace the id of the target section (the part after `#`) with the id on the translated document. For example, it will look like this in Japanese:
+
+Before translation
+
+```
+// in HTML
+<a href="target-file-name.md#target-section-heading-id">Link text</a>
+<a href="#target-section-heading-id">Link text</a>
+
+// in Markdown
+[Link text](target-file-name.md#target-section-heading-id)
+[Link text](#target-section-heading-id)
+```
+
+After translation
+
+```
+// in HTML
+<a href="target-file-name.md#翻訳後の-id">翻訳後のリンクテキスト</a>
+<a href="#翻訳後の-id">翻訳後のリンクテキスト</a>
+
+// in Markdown
+[翻訳後のリンクテキスト](target-file-name.md#翻訳後の-id)
+[翻訳後のリンクテキスト](#翻訳後の-id)
+```
+
+The actual files in docs are written in Markdown, but they will appear as HTML tags on Crowdin.
+
+You can find out how `docsify` converts a string in your language into an id by looking into the translated pages. If the translation is not deployed yet, you can preview it by [running the docs site locally](how-to-work-on-the-docs-theme.md#serving-the-documentation-site-locally).
+
+You can learn more about [internal links in our docs here](how-to-work-on-the-docs-theme.md#how-to-create-an-internal-link).
+
 ## Translate the LearnToCode RPG
 
 The LearnToCode RPG runs on Ren'Py, which uses special syntax for translated strings: (See [Ren'Py Text documentation](https://www.renpy.org/doc/html/text.html))

docs/how-to-work-on-the-docs-theme.md

@@ -1,11 +1,36 @@
-# How to work on the docs theme
+# How to work on documentation
+
+## Work on the docs content
+
+To work on the contributing guidelines, you can edit or add files in the `docs` directory [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/main/docs). When your changes are merged, it will be made available automatically at the documentation site.
+
+### How to create an internal link
+
+If you want to create a link targeting a different section of the contributing guidelines, follow this format:
+
+```md
+[Link text](target-file-name.md#target-section-heading-id)
+
+// If the target section is within the same page, you can omit the file name
+[Link text](#target-section-heading-id)
+```
+
+Make sure you include the file extension (`.md`). Don't specify the full URL or append `/` before the file name.
+
+This is necessary to make these links work for the translated version of the document. Otherwise, they will redirect to the English version of the page regardless of the language.
+
+#### Translating docs with internal links
+
+When you work on translating docs on Crowdin, make sure to replace the `#target-section-heading-id` with the id on the translated document. [Learn more about translating docs here](how-to-translate-files.md#translate-documentation).
+
+## Work on the docs theme
 
 > [!NOTE]
 > A quick reminder that you do not need to setup anything for working on the content for the documentation site.
 >
-> To work on the contributing guidelines, you can edit or add files in the `docs` directory [available here](https://github.com/freeCodeCamp/freeCodeCamp/tree/main/docs). When your changes are merged, it will be made available automatically at the documentation site.
+> To work on the contributing guidelines, see [work on the docs content](#work-on-the-docs-content) section.
 
-## Structure of the docs website
+### Structure of the docs website
 
 The site is generated using [`docsify`](https://docsify.js.org), and served using GitHub pages.
 
@@ -17,7 +42,7 @@ Typically you would not need to change any configuration or build the site local
 - The homepage is generated from the [`_coverpage.md`](_coverpage.md).
 - the sidebar navigation is generated from [`_sidebar.md`](_sidebar.md).
 
-## Serving the documentation site locally
+### Serving the documentation site locally
 
 Clone freeCodeCamp:
 
@@ -40,13 +65,13 @@ docsify serve docs
 
 Alternatively, if you have installed freeCodeCamp locally (see the local setup guide), we bundled the CLI with the development tools so you can run any of the below commands as needed from the root of the repo:
 
-### Serve and launch the documentation site only
+#### Serve and launch the documentation site only
 
 ```console
 npm run docs:serve
 ```
 
-### Serve the documentation site alongside freeCodeCamp locally:
+#### Serve the documentation site alongside freeCodeCamp locally:
 
 ```console
 npm run develop