riverpod icon indicating copy to clipboard operation
riverpod copied to clipboard

Migrate the translation of code-snippets inside the `website/i18n` folder to new string interpolation mechanism

Open rrousselGit opened this issue 4 months ago • 0 comments

Background

In https://riverpod.dev website, code snippets are plain .dart files that are then imported using the syntax:

import myCodeSnippet from "!!raw-loader!./path/to/coode_snippet.dart";

Then passed to <CodeBlock/>/<CodeSnippet/>/<AutoSnippet/>.

An example can be found here:

For the page https://riverpod.dev/docs/concepts/about_code_generation, the source can be found at: https://github.com/rrousselGit/riverpod/blob/a54f32fec6207873377bc665dad1b11fa2106bb9/website/docs/concepts/about_code_generation.mdx#L27

This line imports the following file: https://github.com/rrousselGit/riverpod/blob/a54f32fec6207873377bc665dad1b11fa2106bb9/website/docs/concepts/about_codegen/provider_type/auto_dispose.dart

The file imported is then later used here: https://github.com/rrousselGit/riverpod/blob/a54f32fec6207873377bc665dad1b11fa2106bb9/website/docs/concepts/about_code_generation.mdx#L214

When it comes to translating the file, translations duplicate the .dart files and edit the comments to the new language. For example, a variant of the previous code-snippet can be found in Korean here: https://github.com/rrousselGit/riverpod/blob/master/website/i18n/ko/docusaurus-plugin-content-docs/current/concepts/about_codegen/provider_type/auto_dispose.dart

Task

Moving forward, we would want translations to stop duplicating the original .dart files. Instead, a string interpolation mechanism has been put in place.

The idea is to insert inside the English code-snippet some keys. An example can be found here: https://github.com/rrousselGit/riverpod/blob/master/website/docs/advanced/select/select_async/raw.dart#L16

Then, translations should no-longer duplicate the English file. Instead, they should import the original English file. For example, here is the Korean translation importing the English code snippet: https://github.com/rrousselGit/riverpod/blob/a54f32fec6207873377bc665dad1b11fa2106bb9/website/i18n/ko/docusaurus-plugin-content-docs/current/advanced/select.mdx#L7

The imported file is then used slightly differently. It is now inserted in the document with an extra parameter, corresponding to a map of translations:

https://github.com/rrousselGit/riverpod/blob/c40bb69eb22169157e8c1a1d23836689373b15c8/website/i18n/ko/docusaurus-plugin-content-docs/current/advanced/select.mdx#L60

Notice how the key passed in the translation object corresponds to the name of the "template" in the code snippet ({@template watch})

The goal is to apply this logic to all code-snippets in the website folder.

rrousselGit avatar Feb 11 '24 15:02 rrousselGit