Add i18n support with middleman features

[benzookapi]

Hi, I would like to host our API docs as multilingual pages using middleman i18n features so made a small change to the source. Hope this change will contribute to others who have the similar needs so opening this pull request to base fork.

The following is how to i18n your slate sites.

1. Follow the middleman i18n steps, create the directory "localizable" under the "source" and move "index.html.md" there and create the directory "locales" under the root and put your target message files (e.g. "en.yml", "ja.yml"...) The details is: https://middlemanapp.com/advanced/localization/
   (This is not included by my PR, done by users)

2. Embed "t(:YOUR_MESSAGE_KEY)" in index and other included .md files to where you want to i18n.
   e.g.
   index.html.md
   title: t(:title)
   --
   en.yml
   en:
   title: "My Title"
   --
   ja.yml
   ja:
   title: "私のタイトル"

3. now you can see "My title" in "YOUR_URL/en" and "私のタイトル" in "YOUR_URL/ja". How you can manage the path for localization is fully controlled by middle man i18n above.

4. This localization is applied to HTML title and page content and footers.

[musikele]

Hi, very nice addon. Can this be adapted to show, for example, various versions of the same documentation? For example if I create a locale "v1", a locale "v2", will I be able to modify the content of all texts and examples?

[benzookapi]

@musikele thank you for the comment. v1 and v2 can be used as locales themselves and you can change the texts based on each version, but for examples in lang. panes (shell, node, json...), my t(***) doesn't work correctly... basically i18n approach is designed for localization and if you want version control features, we'd better integrate slate original function.
My idea is that locale resources are handled as langs (en, ja...) and each key in each locale has version info. (text_v1, text_v2 or YAML structure
v1:
text:
v2:
text)

Code examples of each version should be managed in a different way by slate because it is not related to localization, but to API design itself.

[veganstraightedge]

+1 I'd also like to use localization in our API docs at work.

[lord]

Hi, sorry for the delay in reviewing this PR! Unfortunately I can't merge this change into master, since a regex like this would break existing sites that have t(some text here) in their headers, and I'd rather keep the code we have in master as simple as possible. That said, I think this is a very important issue for a lot of sites, so I've created the Internationalization wiki page with your suggestions from this PR. How does it look? Thoughts?

[benzookapi]

@lord Hi, thank you for your review and I understand your comment. Agree, this is a bit temporary patch with minimum code change and we'd better design the best way with minimum issues. I will make better idea and post it in wiki.

[JacobustcZhi]

@benzookapi My project need to support english and chinese. The index in index.zh.html.md.erb , _REST.md.erb and _Websocket.md.erb failed to list level two title in sidebar for chinese page，the default english page show right. likes I18t can not support chinese index? how to set up to support chinese index?
how should I config or setup slate to support the index using includes directory?
I set up the directory like the below

./locales
en.yml
zh.yml

./source/include
_REST.md.erb
_Websocket.md.erb

./source/localizable
index.html.md.erb
index.zh.html.md.erb

[benzookapi]

@JacobustcZhi

Hey, this doesn't limit supported languages so Chinese should work.

./locales
en.yml
zh.yml

This should be OK, make sure your yml has the following structure:

en.yml

en:
  your_key: 'My English text'

zh.yml

zh:
  your_key: 'My Chinese text'

./source/include
_REST.md.erb
_Websocket.md.erb

In my case,

./source/includes
_REST.md
_Websocket.md
(put s to include, remove .erb)

The files should have:

t(:your_key)

./source/localizable
index.html.md.erb
index.zh.html.md.erb

In my case,

./source/localizable
index.html.md
(remove .erb and delete index.zh.html.md.erb)

index.html.md should have:

t(:your_key)

Under this structure,

if you access to YOUR_URL/en,

t(:your_key) shows My English text,

if you access to YOUR_URL/zh,

t(:your_key) shows My Chinese text

Hope this helps you.

[q1097143310]

Hello, whether this plug-in is used for page switching or own language switching? I didn't attain the effect of language switching after following the steps?

[benzookapi]

@q1097143310

You need to activate middleman i18n, I followed this step.
https://middlemanapp.com/advanced/localization/

My config.rb has this line.

activate :i18n, :langs => [:ja, :en], :mount_at_root => :ja

Hope this works for you.

[amirmeimari]

Hey wassup!

I have followed the instructions but my keys are showing up as strings in the output.

my config.rb file has this config: activate :i18n, :langs => [:en, :fa], :mount_at_root => :en

my file structure:

|-lib
|-source
	|--locales
		|--en.yml
		|--fa.yml
	|--localizable
        |--index.html.md
|-config.rb and bunch of other files

this is what I have in my MD file: title: "t(:title)" <%= I18n.t(:title) %> World <%= t(:title) %> World
(also title: t(:title) (without double quotations) is not working)

en.yml:

---
en:
  title: 'yo yo'
  apiKey: 'APIKEY'

fa.yml:

---
fa:
  title: 'یو یو'
  apiKey: 'ای پی ای کی'

and this is the output in the browser:

it seems that slate can't read and parse the translation files!

[benzookapi]

@amirmeimari
My structure is here:

|-lib
|-locales
       |--en.yml
       |--ja.yml
|-source
       |-localizable
                |--index.html.md
|-config.rb

Your structure seems wrong.

If it's still not showing the text, try to remove " from the index.html.md. (and I feel <%= %> won't work in the md file)

[amirmeimari]

@benzookapi

I've changed the file structure and removed " but it's now working :(

Is there any working example code that I can take a look at?

[amirmeimari]

@benzookapi

I've fixed the issue. Thanks :)

[linxux]

Hi @benzookapi ,

Seems it doesn't work for the files under includes.

.
├── locales
│   ├── en.yml
│   └── fr.yml
├── source
│   ├── includes
│   │   ├── _intro.md
│   ├── localizable
│   │   └── index.html.md
...

intro.md

# t(:intro)

Result,

translation missing: en.intro

[benzookapi]

@linxux

My source/includes/_errors.md works fine with these like 't(:note)'. (sorry I am not sure of "_intro.md")

Your index.html.md works fine?

[linxux]

@benzookapi
Thanks for your response.
My bad. Found out I forgot to reload the locales folder with docker.

[aksld]

Hello,

t(:hello) is not interpreted

Do I need to do something more ?

[jiyanyao]

It works fine.
My structure is:
.
|---- locales
|---- |-----en.yml
|-----|-----zh.yml
|-----source
|-----|----- includes
|-----|-----|-----_errors.md.erb
|-----|----- localizable
|-----|----- |------ index.html.md.erb
|-----lib
config.rb
...

in config.rb, add this line: activate :i18n, :langs => [:zh, :en], :mount_at_root => :en

in "_errors.md.erb" and "index.html.md.erb" , use the message <%=t(:errors)%>