docs: added instructions for i18n

README.md

@@ -30,8 +30,8 @@ Tutorials live inside `content`. Each tutorial consists of a `README.md`, which
 
 Bump the dependency (for example Svelte) in both the root and the `content/common` `package.json`. In the root do `pnpm i` (to update `pnpm-lock.yaml`), in `content/common` do `npm i` (to update `package-lock.json`).
 
-## i18n
+## Translating this project
 
 This is the french version of the Svelte tutorial.
 
-If you are willing to fork this project and translate it into your own language, you will need to add the `PUBLIC_SVELTE_SITE_URL`, `PUBLIC_KIT_SITE_URL`, `PUBLIC_LEARN_SITE_URL` and `PUBLIC_GITHUB_ORG` to your environment variables to point to your local Svelte sites and Github organization.
+Read more about this was done [here](i18n.md).

i18n.md

@@ -0,0 +1,191 @@
+# i18n
+
+You'll find in this section some information about the process we used to translate the Svelte tutorial to french. You can check this [draft PR](https://github.com/sveltejs/learn.svelte.dev/pull/514) to get an idea of the different files we modified.
+
+You can find the translated version at the following address: https://apprendre.sveltefr.dev.
+
+## Fork
+
+**We recommend that you fork the [original Svelte tutorial repo](https://github.com/sveltejs/learn.svelte.dev)** rather than this one to keep the original repo as reference.
+
+Either way, you should know that the main modifications we made to original repo are the following :
+- removed original workflows
+- added docs tracking workflow
+- modified Github templates
+- modified a little markdown processing
+- translated UI elements
+- translated the tutorial (of course)
+
+### Opening PRs
+
+On Github, when you open a PR on a forked repo, the PR will by default target to original repo. In our case, this ended up in opening half a dozen irrelevant PRs on Svelte repo, that we had to close right after.
+
+**When opening PRs for submitting a translation to your own repo, make sure to target your own repo** rather than the original one.
+
+## Workflows
+
+### Original workflows
+
+As opposed to [our translation work on the Svelte docs](https://github.com/Svelte-Society-Fr/svelte/blob/french/i18n.md#original-workflows), we chose here to keep the original workflow, to make sure the experience still runs correctly after our modifications.
+
+### Docs tracking workflow
+
+We want these docs to be as close as possible to the original ones. This means keeping them up-to-date as much as possible. For that reason, being notified of changes on the docs is very important.
+
+**We added a custom workflow** called "Docs Tracker" in the file `.github/workflows/track-docs.yml`, based on [AlexxNB's custom Github Action](https://github.com/AlexxNB/track-commits-to-issue). It is composed of one job:
+- "Checking Docs" to monitor changes to the `content/tutorial` folder
+
+This job will check every 3 hours if commits have affected files the provided folder, and publish issues to your repositories with links to said commits. It will be then up to you to mitigate whether or not you need to update your translations.
+
+**We recommend to activate this tracking workflow from day one** of your translation process. From there, you mainly have two options:
+- regurlarly rebase on top of `sveltejs/learn.svelte.dev` to get the latest version of the docs, add new translations if any or fix potential conflicts if changes were made to already translated parts, and close corresponding issues when addressed
+- work only from your original fork and let the issues pile up. Once you're done, perform one rebase, and address the issues one by one
+
+We feel the first option is safer, but you might have a different opinion.
+
+## Github templates
+
+The original repo has some templates for posting issues and Pull Requests. These templates are not relevant in our case since we are _not_ willing to push anything to Svelte's repo. Moreover, we do not want people to accidently open issues or PRs concerning Svelte bugs or feature requests in our translated repository.
+
+For this reason **we modified the templates** to invite people to make sure they are posting their issue or PR to the correct repository depending on their needs.
+
+## UI elements
+
+Most of the translation work is related to the `content/tutorial` folder. But **there are also some UI elements you might want to translate** to make your version complete.
+
+Some of these UI elements are located directly in the Svelte tutorial repo, others are handled by a another repo ([site-kit](https://github.com/sveltejs/site-kit)), common to all Svelte sites ([Svelte](https://svelte.dev), [SvelteKit](https://kit.svelte.dev), and the [tutorial](https://learn.svelte.dev)). This repo provides components with slots and props to handle translations.
+
+You shouldn't have to fork site-kit to provide your translations, but occasionally the Svelte team might modify some elements in the repo and forget about some i18n needs. In that case, open an issue/PR in the site-kit repo to ask for modifications.
+
+Here's the list of files in which you might need to translate UI stuff:
+- `src/lib/server/content.js`
+- `src/routes/+layout.svelte`
+- `src/routes/nav.json/+server.js`
+- `src/routes/tutorial/[slug]/+page.svelte`
+- `src/routes/tutorial/[slug]/Loading.svelte`
+- `src/routes/tutorial/[slug]/Menu.svelte`
+- `src/routes/tutorial/[slug]/Sidebar.svelte`
+- `tests/env_file.spec.ts` (only for tests purposes)
+
+> Be careful, this list might not be exhaustive.
+
+Additionally, you also might want to change the `lang` attribute in `src/app.html`.
+
+## Environment variables
+
+You will need some environment variables, that you can set in the `.env` file if you need them locally, or in your deployment environment if you need to [deploy](#deploying).
+
+### External links
+
+The docs contains references to external sites, such as the [SvelteKit site](https://learn.svelte.dev), the [tutorial site](https://learn.svelte.dev), or the [Github organization](https://github.com/sveltejs/svelte).
+
+In order to be able to easily customize these links, **we added environment variables** representing these links:
+- `PUBLIC_SVELTE_SITE_URL`: URL of the Svelte site
+- `PUBLIC_KIT_SITE_URL`: URL of the SvelteKit site
+- `PUBLIC_LEARN_SITE_URL`: URL of the tutorial site
+- `PUBLIC_GITHUB_ORG`: name of the Github organization/account that hosts this project
+
+At first, the `PUBLIC_KIT_SITE_URL` and `PUBLIC_LEARN_SITE_URL` variables might be just references to the original sites, and not provide any added value. But once you complete the translations of Kit and tutorial docs sites, you might need to use these variables to reference the URLs of your translated sites.
+
+The `PUBLIC_GITHUB_ORG` variable is mainly used to provide a link to your repo when inviting people to "Edit this page".
+
+We might want to use these variables in the following files:
+- `src/routes/+layout.svelte`
+- `src/routes/tutorial/[slug]/Loading.svelte`
+- `src/routes/tutorial/[slug]/Sidebar.svelte`
+
+> Be careful, this list might not be exhaustive.
+
+### Markdown processing
+
+As we have seen in the previous section, the docs contains references to external sites. You might want to also reference these links in the `.md` files, but this will require to **replace the environment variables at build time**.
+
+This can done in the `src/lib/server/markdown.js` file, like so:
+
+```js
+// ...
+		(await marked.parse(
+			markdown
+				.replace(/PUBLIC_SVELTE_SITE_URL/g, PUBLIC_SVELTE_SITE_URL)
+				.replace(/PUBLIC_KIT_SITE_URL/g, PUBLIC_KIT_SITE_URL)
+				.replace(/PUBLIC_LEARN_SITE_URL/g, PUBLIC_LEARN_SITE_URL)
+				.replace(/PUBLIC_GITHUB_ORG/g, PUBLIC_GITHUB_ORG)
+		)) ?? ''
+// ...
+```
+
+## Translating the docs
+
+The core of the work to accomplish is in the `content/tutorial` folder.
+
+**We translated as much as possible in this folder**, even the code snippets so that even code examples are better understood.
+
+Do not forget to translate the `meta.json` files, which provide metadata like section titles.
+
+We did not feel necessary to translate the folder names, since it would 'only' affect URLs. This might have an bad influence on SEO. However, the subsections titles in the `.md` files that you will eventually translate will break links throughout your site. You will need to fix those before deployment.
+
+### AI tools
+
+**We did not use AI tools** to translate these docs. An attempt was made at the beginning of the project, but there were many mistakes and hallucinations, which resulted in extra time checking the generated text. Plus, it felt better to manually control the tone and variations of each sentence, even if it meant writing every word of it.
+
+You might feel differently about AI tools, use them if you find them relevant.
+
+## Glossary
+
+In a web development context, some words do not translate well in some languages – or at least in french –, even if they technically have an official translation. This is because people have taken the habit to use the original word in english rather than the translated one. These are called _anglicisms_.
+
+For example, in french, _callback_ should be translated to _fonction de rappel_. But in practice almost nobody uses the translated word, and we stick to _callback_ instead.
+
+For this reason, **we chose to remain as close as possible to the actual usage**, and keep such words in their original version.
+
+But such anglicisms might not be fully understood by some people, especially beginners in tech. So we added an [extra glossary section](https://sveltefr.dev/docs/development) in the Svelte docs in order to provide a simple definition of the anglicisms.
+
+**Please note that the anglicisms used in this repo are linked to Svelte docs site**, using the `PUBLIC_SVELTE_SITE_URL` variable.
+
+The glossary is divided in four sections:
+- `01-development`: generic development-related words
+- `02-web`: web-related words
+- `03-javascript`: javascript-related words
+- `04-sveltejs`: svelte-related words
+
+We tried not to be too specific in the definitions of this glossary, providing instead links to Wikipedia or MDN.
+
+> Depending on your language and on how people use anglicisms for technical words, your glossary sections might be very different from the french one, or **you might not even need such glossary**. It's up for you to decide really.
+
+### Styling links
+
+To differentiate the anglicisms links from regular links, we added some styling in `src/routes/+layout.svelte`:
+
+```css
+:global(.text .vo a) {
+	color: var(--sk-text-1);
+	box-shadow: inset 0 -1px 0 0 var(--sk-text-4);
+	transition: color 0.2s ease-in-out;
+}
+
+:global(.text .vo a:hover) {
+	color: var(--sk-text-3);
+}
+```
+
+> `'vo'` stands for "original version" (_version originale_) in french, and is what we use to describe movies that aren't dubbed.
+
+> We tried to keep this styling as light as possible to avoid disturbing the reading. Feel free to change it.
+
+A typical link in a `.md` for anglicisms would look like this `<span class='vo'>[callback](PUBLIC_SVELTE_SITE_URL/docs/development#callback)</span>`.
+
+## Discord
+
+If you have a Discord server for your language, you might want to reference it in the `sites/svelte.dev/src/routes/chat/+server.js` file.
+
+## Deploying
+
+Thanks to SvelteKit, it should be quite easy to deploy this project.
+
+**The original site is deployed using [Vercel](https://vercel.com/), and we chose to do the same**. So we can not provide specific troubleshooting for other deployment strategies.
+
+For your deployment to succeed, you need to:
+- make sure your [environment variables](#environment-variables) are correctly set in your deployment environment
+- run `npm run build` to make sur you did not break any links by translating subsection titles (and if so, fix the links)
+
+And if this goes well, the only extra thing you might need is your dedicated domain name! :fire: