Skip to content

Translation delivery notes

Jump to bottom
Rand McKinney edited this page Dec 23, 2015 · 1 revision

Delivery

IMPORTANT: Get content for translation from the i18n branch: https://github.com/strongloop/expressjs.com/tree/i18n.

To get this branch:

git clone -b i18n https://github.com/strongloop/expressjs.com.git

All files to be translated are

  • _includes/header/header-en.html
  • _includes/footer/footer-en.html
  • _includes/notice/notice-en.md
  • en directory (see below). Translate all the below except those marked "DO NOT TRANSLATE".
api.md - DO NOT TRANSLATE (API documentation)

index.md 

/3x: DO NOT TRANSLATE 

/4x: DO NOT TRANSLATE (API documentation)

/advanced:
best-practice-performance.md	
best-practice-security.md	
developing-template-engines.md
pm.md
security-updates.md

/guide:
behind-proxies.md		
database-integration.md		
debugging.md			
error-handling.md		
migrating-4.md			
migrating-5.md
routing.md
using-middleware.md
using-template-engines.md
writing-middleware.md

/resources:
applications.md	- DO NOT TRANSLATE
books-blogs.md - DO NOT TRANSLATE
community.md	
glossary.md	
middleware.md

/starter:
basic-routing.md	
generator.md		
installing.md
faq.md			
hello-world.md		
static-files.md

Languages

Here are langs planned for initial translation:

  • German
  • French
  • Italian
  • Spanish
  • Brazilian Portuguese
  • Japanese
  • Simplified Chinese
  • Traditional Chinese
  • Russian
  • Korean

Mark community vs. official translations

It probably makes sense for us to mark the pages that we translate vs. those contributed by the community.

Format changes

These are changes that we will make in the English source files:

  • Code blocks (triple-tildes)
  • Add lang directive to intrasite links
  • Add comments to YAML header

NOTE: I am asking the globalization team to make the requisite line ending changes from LF to CRLF.

Code blocks

We currently use the following for a block of JavaScript or shell script:

~~~js
... //JS code
~~~

This is equivalent to:

<pre><code class="language-javascript" translate="no">
...
</code></pre>

And

~~~sh
... //Shell commands
~~~

Is equivalent to:

<pre><code class="language-sh" translate="no">
...
</code></pre>

NOTE: With the current CSS, you have to put the HTML tags on the same line as the first line of code (and likewise for the closing tags). If we use it everywhere, then we should fix the CSS so the tags can be on separate lines.

Language directive

For intra-site links, use {{ page.lang }}/ to insert the lang code. However, these are currently NOT in the English content, and just adding them does not work. We should be able to sort this out so it becomes a "no op" for translation.

EXCEPTION: Because API docs are not being translated, do not add the lang. directive to links to the api doc.

Page header

In the Jekyll header only the title text should be translated:

---
layout: page
title: Express database integration
menu: guide
lang: en
---

We can enclose this with YAML comments for the translators, like this:

---
### TRANSLATION INSTRUCTIONS FOR THIS SECTION:
### TRANSLATE THE VALUE OF THE title ATTRIBUTE AND UPDATE THE VALUE OF THE lang ATTRIBUTE. 
### DO NOT CHANGE ANY OTHER TEXT.                                                                                      
layout: page
title: Express basic routing tutorial
menu: starter
lang: en
### END HEADER BLOCK - BEGIN GENERAL TRANSLATION
---
...

Omit from translation

These pages probably shouldn't be translated. While these are useful, they aren't really part of the technical documentation:

Existing translations

Lang Most recent commit No. translated pages Comments Recom-
mendation
es 3-15-2015 2 Translate
ja 9-1-2015 6 Home page plus /starter content translated. Retranslate or translate remainder
ru 11-09-2015 6 Home page plus /starter content translated. Retranslate or translate remainder
zh 9-20-2015 6 Home page plus most /starter content translated. Retranslate or translate remainder
ko 6-13-2015 2 Home page plus installation translated. Translate.
pt-br 11-13-2015 All Very recent Keep. Translate new content.
Clone this wiki locally