# Add French or another language

> Adding a language, keeping short texts and longer writing in each language, translating data, and what publishing checks.

For builders whose customer has a website in more than one language.
It covers adding a language, keeping short texts and longer writing in each language, translating data, and what publishing checks. At the end, Saltmere Marina is in English and French: each page, the header's menu, the news post and the weather, with a link between the two languages.

A site comes in every language of the website the business has now. The marina's website today is in English and French, so this one is too. Each page is written once, with its HTML and Liquid shared by every language. Only the words change, in two ways:

- **Strings,** the short texts such as headings, menu labels and buttons, each with a name, go in one file per language in the `locales` folder, and pages print them with the `t` filter.
- **Longer writing,** such as a paragraph about the marina, goes in a `{% text %}` block in the page, with a part for each language.

`ws push` refuses a site with anything missing in a language, and names each one. `ws preview` builds anyway, so you can look at the site between the steps below: it shows the main language wherever a translation is missing, and lists what is missing.

## 1. Add the language

```
$ ws site --languages en,fr
Saved: "Saltmere Marina" is in English (main) and French.
Every page is now built in French too, at an address starting with /fr.
Strings go in locales/fr.json, and French data files in _data/fr/.
```

The first language is the main one, at `/`. `about.html` now makes two pages: `/about` in English and `/fr/about` in French. Before the first publish, a setting is saved with the site and goes into version 1. After that, a change to a setting makes a new version, like a change to a file.

Run `ws preview` now and it lists everything French still lacks, such as the French news post. The French pages show the English words there until you add them.

## 2. Move the strings into the locales files

Make `locales/en.json`, with the words the header and home page use:

```json
{
  "menu": { "home": "Home", "about": "About" },
  "home": { "title": "Home", "news": "News", "date": "%B %-d, %Y" },
  "weather": { "now": "At the marina", "wind": "wind", "link": "Weather for Saltmere", "site": "https://weather.gc.ca" }
}
```

And `locales/fr.json`, with the same names and the French words:

```json
{
  "menu": { "home": "Accueil", "about": "À propos" },
  "home": { "title": "Accueil", "news": "Nouvelles", "date": "%-d %B %Y" },
  "weather": { "now": "À la marina", "wind": "vent", "link": "Météo pour Saltmere", "site": "https://meteo.gc.ca" }
}
```

The `locales` folder is never published. `{{ 'menu.about' | t }}` prints the word named `about` inside `menu`, in the page's language: "About" on an English page, "À propos" on a French one. Names nest this way: a key written as `"menu.about"` is one name with a dot in it, which `t` does not read. Shopify themes keep their words the same way.

Then change `_includes/header.html` to use them, and add a link to the same page in the other language:

```html
<header>
  <a href="{{ '/' | lang_path }}" class="name">{{ site.name }}</a>
  <nav>
    <a href="{{ '/' | lang_path }}">{{ 'menu.home' | t }}</a>
    <a href="{{ '/about' | lang_path }}">{{ 'menu.about' | t }}</a>
    {% for other in page.translations %}
      <a href="{{ other.path }}" hreflang="{{ other.lang }}">{{ other.name }}</a>
    {% endfor %}
  </nav>
</header>
```

`lang_path` turns a page's main address into its address in the page's language, so on a French page `'/about' | lang_path` is `/fr/about`. `page.translations` lists the same page in the site's other languages, each with its `path`, its language code `lang`, and the language's own `name`, such as "Français".

## 3. Write longer text in each language

Change `about.html`:

```html
---
layout: default
title: "{{ 'about.title' | t }}"
addresses: { fr: /fr/a-propos }
---
<h1>{{ 'about.title' | t }}</h1>

{% text %}
Saltmere Marina has 140 slips on the south shore of Nova Scotia.
The Doucet family has run it since 1987.
{% in 'fr' %}
La marina Saltmere compte 140 places sur la rive sud de la Nouvelle-Écosse.
La famille Doucet l'exploite depuis 1987.
{% endtext %}

<img src="/photos/dock.jpg" alt="{{ 'about.photo' | t }}">
```

Add the new names, `about.title` and `about.photo`, to both locales files. Do the same for the labels of the slip request form on the About page, such as Name and Email. The `thanks` field uses `lang_path` too, so a French visitor lands on the French thank-you page:

```html
<input type="hidden" name="thanks" value="{{ '/thank-you' | lang_path }}">
<label>{{ 'form.name' | t }} <input name="name" required></label>
<label>{{ 'form.email' | t }} <input name="email" type="email" required></label>
```

`thank-you.html`, the page the form's `thanks` field opens, needs its French words too. Put them in a `{% text %}` block, as on the About page, so the French form lands on a French page.

The `{% text %}` block holds the writing in Markdown, first in the main language. Each `{% in 'fr' %}` starts the same writing in another language, and `{% endtext %}` ends the block. A page prints only the part in its own language.

The block is Markdown, so Liquid inside it, such as `{{ site.name }}`, prints exactly as typed. Keep Liquid outside the block, or put those words in the locales files and print them with `t`. `ws preview` and `ws push` warn about Liquid inside a block and name the line.

`addresses: { fr: /fr/a-propos }` in the front matter gives the French page an address in French. Without it, the French page is at `/fr/about`. `lang_path` and `page.translations` use the address given here.

Change `index.html` the same way. Its heading and welcome text go in a `{% text %}` block, and the words around the news list and the weather come from `t`:

```html
<h2>{{ 'home.news' | t }}</h2>
{% assign date_format = 'home.date' | t %}
{% assign posts = data.news | sort: "date" | reverse %}
{% for post in posts limit: 3 %}
  <article>
    <h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
    <p>{{ post.date | date: date_format }}</p>
  </article>
{% endfor %}

{% live 'weather' %}
  <p>{{ 'weather.now' | t }}: {{ live.item.temperature }} °C,
  {{ 'weather.wind' | t }} {{ live.item.wind }}.</p>
  <ul>
    {% for period in live.items limit: 4 %}
      <li>{{ period.name }}: {{ period.summary }}</li>
    {% endfor %}
  </ul>
  <p><small>{{ live.credit }}</small></p>
{% fallback %}
  <p><a href="{{ 'weather.site' | t }}">{{ 'weather.link' | t }}</a></p>
{% endlive %}
```

When a visitor opens the page, the platform fills the `{% live 'weather' %}` part with the newest weather it has fetched from Environment Canada, and shows the part after `{% fallback %}` when Environment Canada has not been reached for 3 hours. [Part 4](https://docs.websitestrategy.com/guides/add-news-weather-forms/#3-the-weather-at-the-marina) explains both. On the French page, the forecast's names and summaries, such as "Ce soir : Généralement nuageux", the wind direction and the credit line come from Environment Canada in French. The date format comes from the locales files too, so the post's date prints as "November 2, 2026" in English and "2 novembre 2026" in French.

## 4. Translate the news

French data files go in `_data/fr/`, with the same file names as the English ones. Only records in a data folder are translated this way, since the folder's schema says which fields are written in each language. A single file such as `_data/hours.yml` has no schema, so keep its words in the locales files, or make it a folder. Make `_data/fr/news/2026-11-02-fuel-dock.md`:

```markdown
---
title: Le nouveau quai de carburant est ouvert
slug: quai-carburant
---
Le diesel et l'essence sont au bout du quai B, de 7 h à 19 h. Le diesel coûte 1,79 $ le litre.
```

The French file holds only the fields the news schema, `_data/news.schema.yml`, marks `translate: true`, and the post's text. The date is not in it: the French post uses the English file's date, so the two cannot disagree.

The one page file `news/[slug].html` makes the post pages in both languages. Give its French pages a French address:

```html
---
layout: default
each: news
title: "{{ item.title }}"
addresses: { fr: /fr/nouvelles/[slug] }
---
<h1>{{ item.title }}</h1>
{{ item.body | markdown }}
```

On a French page, `item` holds the French title, slug and text, so this post is at `/fr/nouvelles/quai-carburant`. `post.url` on the French home page links there.

## 5. What publishing checks

Suppose you had added `about.photo` to the English strings file only, and skipped step 4. Then publishing stops:

```
$ git add -A && git commit -m "French"
$ ws push
Not published: these are missing in French.
  locales/fr.json has no "about.photo" (used in about.html, line 16).
  _data/fr/news/2026-11-02-fuel-dock.md is missing.
```

`ws push` refuses a site where any language is missing a string, a part of a `{% text %}` block, a data file's translated fields or a page address. Add what it lists and publish again. A page whose words come out the same as in the main language, such as a thank-you page written only in English, gets a warning from `ws preview` and `ws push` on engine release 2; engine release 3 will refuse it. `ws preview` lists the same things but still builds. A page meant for one language only, such as a notice for French readers, says so in its front matter with `languages: [fr]`.

The coding agent the builder works with writes the translations in the same change as the English. Nobody checks them before they are published: agents translate well, and the owner can correct any of them later. If a change alters English text and leaves its French as it was, such as an English spelling fix, `ws push` still publishes, and lists the French lines whose English changed, so you can check you meant it.

## 6. The owner's view of each language

Under **Languages** in the owner panel on `app.websitestrategy.com`, the owner sees each page, string and post side by side: the English on one side, the French on the other. They can correct any French line, and their correction is published like any change.

The platform keeps the owner's wording. If a later change from a builder's copy of the site's folder, sent with `ws push`, would replace a line the owner corrected, `ws push` refuses and names the line. When the English of a corrected line changes, the line is marked in the owner's view, so they can look at it again. Weglot and Shopify's Translate & Adapt app work this way.


