Docs i18n: working prototype

I gave another stab at Gatsby after @Thieffen shared another example of doc i18n over at react-hook-form’s doc repo

Feel free to fork and play with this:


It is unstyled and just a starting point for conversation. I arbitrarily split up the tutorial for sample pages and stole Thieffen’s French translations :slight_smile:

Tech stack

How it works
Markdowns are structured in a directory structure that becomes the url path.

A sidebar nav is generated half-manually. We define translations for section titles, and the order we want markdown files to appear in each section via the paths array.

Titles for each page inside a section is automatically generated from the first header to appear in that markdown file, and links for each language are automatically supplied so you only define the paths once.

const linkPaths: SidebarLinkPaths = {
  Tutorial: {
    sectionTitle: {
      en: "Tutorial",
      fr: "Didacticiel",
    paths: [

A language switcher in the navbar updates the selected language in the global state, which can be accessed from any component using a useLanguageContext() hook.

This architecture would rely on all markdown files sharing the same name in every language (hence the same slug in the url). So there wouldn’t be localized urls


Interested to hear your impressions/concerns

1 Like

Does this mean we will not get a clairejs? :cry: sad-nightingale was an apt Netlify app-name indeed.

Something’s missing on the /fr pages. Normally my browser would offer to translate any French pages, but it doesn’t for this one. And I think having urls that matches the <h1>s would be better for seo (i.e. having localized urls as well)

Very good work @clairefro!
One step after another this is taking shape :+1:

I Don’t really know about untranslated slugs, mismatch H1 and SEO implications. learnstorybook and react websites successfully work with untranslated URL. Also, URL with non-English slugs contains a lot of special chars like ‘à’,‘é’,‘ô’. Since they are usually striped, you still end-up with a H1 mismatch anyway.

Are you able to add versioning in the path (/v1/en/tutorial/…) like in your previous attempt?

I’ll take this opportunity to teach you all a Swedish word for which there doesn’t seem to be an English equivalent

killgissa, literally “guy-guess”. To describe something as if it’s undisputed facts, even though it is really a guess or an assumption.

(Sorry, next time I’ll keep quiet when I obviously don’t know enough about the subject to bring anything meaningful to the conversation :slightly_smiling_face:)

1 Like

So, sometimes this is called “deburring” where ô simply becomes o.

But a nicer option is

slugify('  Déjà Vu!  ');
//=> 'deja-vu'

which also attempts to transliterate

slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'

Which can make for more friendly urls.

Note: apparently someone really loves tattoos.

1 Like

Hey @tobbe, I wanted to say that “I Don’t really know about untranslated slugs”, and not that you don’t. Let me add this to the original post to make it clear I was speaking about my own ignorance :smiley:


`//=> ‘ya-lyublyu-edinorogov’

It means “I love …” and a name … and my Googling of the name’s first hit returned a tattoo artist.

Nikolay Edinorogov . Tattoo artist from Kazakhstan Art tattoo

But now that I Google more it might refer to a cannon or possibly just Unicorns :unicorn: which makes sense since I now recall from my limited Russian that edin is one.

Yeah, it’s :unicorn:s


:unicorn: is what google says too :slight_smile: That’s why I was confused.

1 Like

I just added and deployed some basic SEO with this commit. It adds html lang attribute which might tip off your browser - try navigating to any of the FR tutorial pages like below

(Note: the homepage needs some redirect work TODO later)

1 Like



1 Like

AWESOME @clairefro! Since it’s Tailwind you could plug in the markdown styling from dot com directly! Although if you want to go in a different direction with the styling, feel free! If we aren’t getting ClaireJS, how about ClaireUI??

Does this still get to use gitlocalize for the translations?

I’ll post this before Tom does—when I was working on I was using flags next to languages as well (doesn’t everyone?) and then Tom sent me this link: and now I just use the name of the language in the language it’s spoken in (is there a name for that?).

Very exciting!

Also, Windows doesn’t have emojis for the flags, so all I see is this


Amen :slight_smile: Flags will come down. Especially problematic with colonial languages like French/English/Spanish/Portuguese and especially especially problematic with Chinese

AWESOME @clairefro! Since it’s Tailwind you could plug in the markdown styling from dot com directly!

Good point!

Does this still get to use gitlocalize for the translations?

Not in this demo as it was just to show the repo architecture, but it’s as as easy as un deux trois to integrate it

I haven’t forgotten about this :slight_smile: Will be polishing up this week with a little style so we can get some feedback next meetup

I will include a link to

Thieffen kindly removed the flags and swapped for English/Français :slight_smile: