svelte/i18n.md

# i18n

You'll find in this section some information about the process we used to translate the Svelte docs to french. You can check this [draft PR](https://github.com/sveltejs/svelte/pull/9281) to get an idea of the different files we modified.

You can find the translated version at the following address: https://sveltefr.dev.

## Repo

**We recommend that you fork the [original Svelte repo](https://github.com/sveltejs/svelte)** rather than this one to keep the original repo as reference.

Either way, you should know that the main modifications we made to the 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 docs (of course)
- added a glossary section

### Workflows

#### Original workflows

The original Svelte has some workflows to make sure everything works as expected. **We chose to remove these workflows** to avoid being blocked by CI errors that do not really matter to us. Feel free to keep them if you'd like.

#### 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 three jobs:
- "Checking Docs" to monitor changes to the `documentation` folder
- "Checking Site" to monitor changes to the `sites/svelte.dev` folder
- "Checking Svelte" to monitor changes to the `packages/svelte/src` folder

These jobs will check every 3 hours if commits have affected files in their respective 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/svelte` 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.

### 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.

## Environment variables

You will need some environment variables, that you can set in `sites/svelte.dev/.env` file if you need them locally, or in your deployment environment if you need to [deploy](#deploying).

### REPL

Svelte's REPL use a [Supabase](https://supabase.com/) instance to store user data, which is referenced by the following environment variables:
- `SUPABASE_URL`
- `SUPABASE_KEY`

For development, these variables should already be set in the `.env` (even if the key is `''`), so you do not need to modify them.

However, you will need to set different values for deployment. We obviously can not access Svelte's official Supabase instance, so **we needed to create our own Supabase instance**, and provide these variables with our own values.

More info on how to set up your Supabase instance [here](https://github.com/sveltejs/sites/tree/master/db).

### 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 (not really needed in this repo)
- `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:
- `sites/svelte.dev/scripts/get_contributors.js`
- `sites/svelte.dev/src/routes/(authed)/repl/api/[id].json/+server.js`
- `sites/svelte.dev/src/routes/+layout.svelte`
- `sites/svelte.dev/src/routes/+page.svelte`
- `sites/svelte.dev/src/routes/_components/Hero.svelte`
- `sites/svelte.dev/src/routes/docs/[slug]/+page.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 `sites/svelte.dev/src/lib/server/docs/index.js` file, like so:

```js
category.pages.push({
	// ...
	content: page_content
		.replace(/PUBLIC_KIT_SITE_URL/g, PUBLIC_KIT_SITE_URL)
		.replace(/PUBLIC_SVELTE_SITE_URL/g, PUBLIC_SVELTE_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 `documentation` folder. You will find four folders : `blog`, `docs`, `examples`, `tutorial`.

> You can find more information about these folders and their structure in [this section](sites/svelte.dev/README.md).

### Main content

#### `blog`

**We did not translate anything in this folder**, because of the amount of posts to translate. Some of these posts are quite old, and it might not be very relevant to translate them.

#### `docs`

**We translated as much as possible in this folder**, even some strings in 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 a 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.

#### `examples`

Since we translated code snippets in the `docs`, **we felt necessary to also translate as much as possible in this folder**.

#### `tutorial`

This section is the tutorial that you can access if your browser does not support the modern tools required to display the [`learn.svelte.dev` site](https://learn.svelte.dev). This version of the tutorial can be quite different from the `learn.svelte.dev` one, and would have required extra work we did not consider necessary.

**We did not translate anything in this folder**, but you might feel differently about it.

### UI elements

Most of the translation work is related to the `documentation` 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 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:
- `sites/svelte.dev/src/lib/time.js`
- `sites/svelte.dev/src/routes/(authed)/apps/+page.svelte`
- `sites/svelte.dev/src/routes/(authed)/repl/[id]/+page.svelte`
- `sites/svelte.dev/src/routes/(authed)/repl/[id]/AppControls.svelte`
- `sites/svelte.dev/src/routes/(authed)/repl/[id]/UserMenu.svelte`
- `sites/svelte.dev/src/routes/(authed)/repl/embed/+page.svelte`
- `sites/svelte.dev/src/routes/+layout.server.js`
- `sites/svelte.dev/src/routes/+layout.svelte`
- `sites/svelte.dev/src/routes/+page.svelte`
- `sites/svelte.dev/src/routes/_components/Demo.svelte`
- `sites/svelte.dev/src/routes/_components/Hero.svelte`
- `sites/svelte.dev/src/routes/_components/Supporters/index.svelte`
- `sites/svelte.dev/src/routes/_components/WhosUsingSvelte/index.svelte`
- `sites/svelte.dev/src/routes/blog/[slug]/+page.svelte`
- `sites/svelte.dev/src/routes/docs/[slug]/+page.svelte`
- `sites/svelte.dev/src/routes/examples/[slug]/+page.svelte`
- `sites/svelte.dev/src/routes/nav.json/+server.js`
- `sites/svelte.dev/src/routes/search/+page.svelte`
- `sites/svelte.dev/src/routes/tutorial/[slug]/+page.svelte`

> Be careful, this list might not be exhaustive.

Additionally, you also might want to change the `lang` attribute in `sites/svelte.dev/src/app.html`.

### Interfaces

The 'Types' sections of the docs directly refer to the Svelte compiler source code. For instance, the documentation [here](https://svelte.dev/docs/svelte-store#types-readable) is not written anywhere in the `documentation` folder, but in the compiler source code instead.

If you want the types descriptions to also be translated, then you will need to work on these files:
- `packages/svelte/src/compiler/interfaces.d.ts`
- `packages/svelte/src/runtime/action/public.d.ts`
- `packages/svelte/src/runtime/internal/dev.js`
- `packages/svelte/src/runtime/internal/public.d.ts`
- `packages/svelte/src/runtime/store/public.d.ts`

> Be careful, this list might not be exhaustive.

### AI

**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](documentation/docs/07-glossary) in the docs in order to provide a simple definition of the anglicisms.

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.

### Introduction

Each section of the glossary has the same introduction, which reads as follows:

> You'll find herebelow some information on usual anglicisms used in the context of [X].
> These words do not translate well in french, or their translation is rarely used. We prefer to leave their english version in the docs to remain as close as possible to actual usage.
> This glossary section is specific to the french version of the Svelte docs, and does not exist in the official documentation.


### Styling links

To differentiate the anglicisms links from regular links, we added some styling in `sites/svelte.dev/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](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` in `sites/svelte.dev` 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: