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

REPL

Svelte's REPL use a Supabase 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.

External links

The docs contains references to external sites, such as the SvelteKit site, the tutorial site, or the Github organization.

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:

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.

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. 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), common to all Svelte sites (Svelte, SvelteKit, and the tutorial). 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 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 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:

: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, 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 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! 🔥