Translating the Tutorial (and, maybe, Docs)

Get Involved Docs & Content Translations
82

What we need is so simple… just a static site generator that allows nested dirs and contextual sidebars.

I’m taking a page out of Rob’s book and seeing if I can’t make one

2 Likes
83

Did you register clairejs.com yet?? :smiley:

84

Did you register clairejs.com yet?? :smiley:

Is flaminghotmessjs.com already taken?

1 Like
85

Looks promising.

public
  v1
    en
      tutorial
        welcome-to-redwood.html
        installation.html
      cookbook
        how-to-do-it.html
        how-to-do-something-else.html
    ja
      tutorial
        welcome-to-redwood.html
        installation.html
      cookbook
        how-to-do-it.html
        how-to-do-something-else.html

Versioning in the structure is also probably a good move.

I’ll start to help after finishing first tutorial translation (about 50% done)
Keep up the good work!

2 Likes
86

I’m always impressed by the amount of work people dedicate to open source contributions but building a totally custom multi-lingual static site generator is on another level!

Ideally this works out and ends up serving our needs (in which case we should do a write up and share the project for others going through this same process). But I’ve also done a little more research into alternatives in case we still aren’t satisfied with the current direction.

Vuepress seems to have some pretty powerful internationalization features built-in. It was created by Evan specifically to support the needs of Vue’s docs. Since Vue has a large community of Chinese users its documentation has been multi-lingual from the start. Vuepress itself is composed of two parts:

Here’s the documentation from the Internationalization page of the Vuepress docs:

Site Level i18n Config

To take advantage of multi-language support in VuePress, you first need to use the following file and directory structure:

docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ zh
   ├─ README.md
   ├─ foo.md
   └─ nested
      └─ README.md

Then, specify the locales option in .vuepress/config.js:

module.exports = {
  locales: {
    '/': {
      lang: 'en-US', // this will be set as the lang attribute on <html>
      title: 'VuePress',
      description: 'Vue-powered Static Site Generator'
    },
    '/zh/': {
      lang: 'zh-CN',
      title: 'VuePress',
      description: 'Vue 驱动的静态网站生成器'
    }
  }
}

The key is the path for the locale to be nested under. As a special case, the default locale can use ‘/’ as its path.

If a locale does not have a title or description, VuePress will fallback to the root-level values. You can omit the root level title and description as long as they are provided in each locale.

Default Theme i18n Config

The default theme also has built-in i18n support via themeConfig.locales, using the same { path: config } format. Each locale can have its own nav and sidebar config, along with some other text values used across the site:

module.exports = {
  locales: { /* ... */ },
  themeConfig: {
    locales: {
      '/': {
        selectText: 'Languages',
        label: 'English',
        ariaLabel: 'Languages',
        editLinkText: 'Edit this page on GitHub',
        serviceWorker: {
          updatePopup: {
            message: "New content is available.",
            buttonText: "Refresh"
          }
        },
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/' , ariaLabel: 'Nested' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        }
      },
      '/zh/': {
        selectText: '选择语言',
        label: '简体中文',
        editLinkText: '在 GitHub 上编辑此页',
        serviceWorker: {
          updatePopup: {
            message: "发现新内容可用.",
            buttonText: "刷新"
          }
        },
        nav: [
          { text: '嵌套', link: '/zh/nested/' }
        ],
        algolia: {},
        sidebar: {
          '/zh/': [/* ... */],
          '/zh/nested/': [/* ... */]
        }
      }
    }
  }
}

They also mention a few other options they considered and the problems they encountered:

Nuxt

  • Designed for building applications
  • VuePress is focused on content-centric static sites and provides features tailored for technical documentation out of the box

Docsify/Docute

  • Both fully runtime-driven and therefore not SEO-friendly

Hexo

  • Theming system is static and string-based
  • Markdown rendering isn’t flexible enough for configuration

GitBook

  • Development reload performance is intolerable with a large amount of files
  • The default theme also has a pretty limiting navigation structure
  • The team is focused on turning it into a commercial product rather than an open-source tool
1 Like