This tutorial will show you how to i18n Flarum document.
Flarum docs use Vuepress which is a lightweight static website generator based on Vue. This tutorial focus onn how to i18n flarum documents. For detailed configuration of vuepress, please read the vuepress document.
Guideline
Step 1 : Fork
Step 2 : Clone
Step 3 : Install
Step 4 : Translate and config
Step 5 : Config sidebar
Step 6 : Custom sidebar title
Step 7 : Preview docs website
Step 1 : Fork Upstream Repository
Fork Flarum Document repository to your GitHub Account or other SVN.
Step 2: Clone your forked repository to local system.
clone https://github.com/<username>/docs.git
Here is the project structure:
. ( docs root folder )
├── docs ( the real documents )
│ ├── .vuepress ( **Vuepress config** )
│ │ ├── components ( vue components, to display hints at the top of the docs page. )
│ │ ├── config ( document config )
│ │ │ ├── locales ( **language config** )
│ │ │ │ ├── en
│ │ │ │ │ ├── index.js ( Config site title and language tag )
│ │ │ │ │ ├── nav.js ( Config the navigation bar of the site,
│ │ │ │ │ │ the link entry shoule include the name of the language directory. )
│ │ │ │ │ ├── sidebar ( Config the sidebar of the site, see details in STEP 5. )
│ │ │ │ │ └── theme.js ( Config other things. )
│ │ │ │ ├── tr ( Turkish locale, same structure as en )
│ │ │ │ ├── zh ( Chinese locale, same structure as en ,
│ │ │ │ │ * Folder name and language tag should follow the w3 specification ↓ *
│ │ │ │ │ * https://www.w3schools.com/tags/ref_language_codes.asp *)
│ │ │ │ └── index.js ( active your language docs by adding language code to the langs entry. )
│ │ │ └── head.js ( <head></head> of the site )
│ │ │ └── plugin.js ( what plugin the document need )
│ │ ├── public ( static web assets, like ico, img, .etc)
│ │ ├── styles ( add css styles if your need )
│ │ └── config ( Multi-language support )
│ ├── extend ( English document : /extend )
│ │ └── ······
│ ├── tr ( .md files, documents of Turkish version )
│ │ └── ······
│ └── zh ( documents of Chinese version )
│ ├── extend ( docs : /extend )
│ └── .md files ( docs : /index )
├── .editorconfig
├── .gitignore ( What files that SVN should ignore )
├── LICENSE
├── package-lock.json
└── package.json
Step 3 : Install Vuepress and Dependencies
If you don’t need to preview the docs website locally, skip this step.
Open terminal in root folder of the repository ( the first folder named docs ) :
npm install
If the installation is successful, you will see a folder node_modules.
Step 4 : Translate & Config
- Create your locale folder
- At least translate index docs, before you finish translating the extend document, the extend link in the navigation bar should be directed to the english document
- Config locale configuration files in
/.vuepress/config settings like other language did
Step 5 : details of sidebar.js Configurations
If you haven’t translated all the documents, you can only show docs that you have already translated, just config the sidebar, delete the item you haven’t translated yet :
the original sidebar.js of english docs:
module.exports = {
'/extend/': [ * the extend docs path, a sidebar group *
{ * one section of sidebar group *
title: 'Main Concepts', * title of the section *
collapsable: false,
children: [
'', * README.md, keep it blank *
'start', * /extend/start.md file. Direct reference the file name, *
* the item title will be the h1 title in the markdown file. *
* If you want to custom the tile of the item, see STEP 6*
'frontend',
'routes',
'data',
'distribution',
'update-b8',
'update-b10',
'update-b12',
'update-b13',
'update-b14',
'update-b15',
]
},
…… ( Other section of /extend page)
……
……
],
'/': [ * the index docs path *
{
title: 'Introduction',
collapsable: false,
children: [
'',
'code-of-conduct',
'releases',
'contributing',
'bugs',
'faq'
]
},
…… ( Other section of index page)
……
……
],
}
Step 6 : Custom item title of sidebar
module.exports = {
'/zh/extend/': [
{
title: 'section title',
collapsable: false,
children: [
['','new README title'],
['start','new start'],
]
},
…… ( Other section of /extend page)
……
……
],
…… ( sidebar of index page)
……
……
}
Step 7 : Preview docs website locally
Go to /docs/docs folder and run
npm run dev
then preview : http://localhost:8080/docs