iojs.org vs. localised sites

[Starefossen]

io.js Norway has just begun translating the iojs.org website into Norwegian (see http://iojs.no), and we have some questions regarding structural differences between iojs.org and the localised site.

• Should the localised site visually look the same?
• Should the localised site only have content from the main site or are we free to add our content as well as the translated pages?
• We want to have the blogposts directly on the site / repo, is that ok (see link in top menu)?

I hope someone from the website wg is able to give us some recommendations in this regard 🐻

[stringparser]

The blog idea is really good in fact. Thus far (see last 2 comments of #125), it seems there is no problem.

[therebelrobot]

This is directly related to the #119 PR and the #125 issue. As far as I was aware we weren't looking at separate domains as much as an i18n version of the site on the .org. This will most likely need to be discussed in the next wg meeting. Internal structure on the site is about to change wildly though, so be aware.

• Yes, the localized sites should look the same as all the others for consistency. This is part of why we are looping in i18n into the normal build process.
• The localized content should match what is in every other language, again for consistency.
• the blog is being covered in Static Blog page #68

We do, however, want to make sure all website handling is being looped into and coordinated by our website working group, to ensure everything is up to date, consistent, and up to the TC's standards.

[stringparser]

thanks!

[therebelrobot]

@Starefossen within the next few days we'll have a proper i18n contribution plan in place.

[Starefossen]

Thanks for the update @therebelrobot!

[AntouanK]

How about using different fonts? Or at least trying to find similar fonts with the special language we need?
For example, the font the main website is using, does not have Greek letters, it defaults to sans-serif for greek characters.

Google fonts has plenty of fonts with extra character sets, but I guess there should be a build step where we can add that font.

[therebelrobot]

That is a great question. We could do language specific styling, integrating a new css class using the build process along with a new file in the content folders.... @Fishrock123 @snostorm what do you think?

[Starefossen]

Why is the new site not using submodules for the localised content? Kind of makes no sense with the separate repos, and it makes it extremely cumbersome for the language teams to fix their translations.

Also, are there any mechanisms in place for detecting new additions to the source/english version which should be translated and added to the localised versions?

[therebelrobot]

@Starefossen the translations of the site itself are submodules, found in content/<lang-name> in this repo, and this is where the translated content should reside. The separate repos are for any language specific portals you as a Language Working Group want to build to announce local events or things along those lines. Any sites outside of here, though, should point back to the appropriate language folder (e.g. iojs.org/es for Spanish translation) for anything core related: downloads, FAQ, etc.

As of right now, there is no mechanism in place to notify of new changes to english content for translation, that's something we'll need to brainstorm on.

[Starefossen]

I still think content/<lang-name> should be a submodule pointing to the localised repo such that the language team can update them without having to go create a new PR to iojs/website for every single change.

[therebelrobot]

A good suggestion, and one we can definitely discuss in the WG, though for the time being the PR method is what is implemented. @Fishrock123 @snostorm How difficult do you see this type of thing being refactored?

[ruimarinho]

In that case, I'd suggest using it git subtrees so that the code is readily available after a git clone.

[alexpods]

+1 for pointing content/lang-name to some folder in the localized repo. It'll simplify the work a lot.

[AntouanK]

I was trying to find the Greek character subset for the Lato font, the one you are using, but I couldn't find anything.
Should we open another issue for the font, to see what solutions we can come up with?

[Nicolab]

+1 for pointing content/lang-name to some folder in the localized repo

[snostorm]

Subtree actually might be a great way to go here. A little complicated to manage, but we can handle that on this repo as maintainers (or advanced PR makers).

[snostorm]

@Starefossen I'm open to making your repo the 1st test case for the subtree approach. If it goes well we can document + transition other interested groups.

[Starefossen]

That would be great @snostorm! iojs/iojs-no contains the same files as iojs/website/content/no, with the exception of template.json which I am in the process of adding as we speak. There are however som other files and directories there, not sure if that will be a problem? We are currently using the gh-pages as our primary branch, but we can have the translated files on master as well if that is better for the subtree setup.

Just post what you need me to do and I'll get right on it.

Update:

I have pushed the missing template.json file. However, I see that our index.md file is a bit behind iojs/website with regards to the use of html-code. Also, we use some variables to keep the pages dry (version numbers, links etc.). Those variables will need to be removed in order to be compatible with the iojs.org build which needs plain markdown files.

[snostorm]

Good questions. I don't really have an answer. The think both ends of the subtree can be located sub-folders in each project. iojs/website/content/no/ -> iojs/iojs-no/content/ or iojs/iojs-no/website-content for example. Whatever you want us to point at/track in the end.

[snostorm]

Another interesting thought: this is yet another reason to start using variables for stuff like version numbers. Otherwise when we go to do stuff like 535ae29 one of two things will happen:

• The @iojs/website folder's subtree will now conflict with the "upstream" subtree on iojs/iojs-no (won't be an issue until somebody goes to push a change that conflicts.)
• The PR will have to be approved upstream repos first than pushed down to iojs/website which would be a blocker (non option.)

Anyway, something our experimenting will help figure out.

[Starefossen]

Good questions. I don't really have an answer. The think both ends of the subtree can be located sub-folders in each project. iojs/website/content/no/ -> iojs/iojs-no/content/ or iojs/iojs-no/website-content for example. Whatever you want us to point at/track in the end.

iojs/iojs-no/content/ looks fine by me.

Another interesting thought: this is yet another reason to start using variables for stuff like version numbers.

Yeah, we should find a good way to solve variable stuff. We are currently using jekyll/liquid template variables to keep all our references up to date (iojs-no/index.md).

[JCMais]

Good questions. I don't really have an answer. The think both ends of the subtree can be located sub-folders in each project. iojs/website/content/no/ -> iojs/iojs-no/content/ or iojs/iojs-no/website-content for example. Whatever you want us to point at/track in the end.

What about the iojs-pt project which handles two translations (pt_BR and pt)? How it's going to work?

[snostorm]

@Starefossen Agreed. For high level solutions we try to solve those problems at the website project level so we can share best practices down to the other groups (versus re-inventing the wheel each time.)

Although, at the local level, it may work well to fork processes a bit to allow for some experimentation before passing those lessons back up :)

@JCMais I'd probably suggest we just subtree the two different folders targeting two different ones in the upstream project. There's no reason this shouldn't work, although it may get confusing to maintain.

So maybe iojs/iojs-pt/content-pt and iojs/iojs-pt/content-pt_BR or just simplfy pt and pt_BR.

[Starefossen]

@snostorm I have a PR (nodejs/nodejs-no#39) pending review by the rest of the norwegian language team which has a fresh set of translated markdown-files in the /content directory – ready to be included as a subtree :)

[snostorm]

@Starefossen thanks! I've been experimenting with my proposal this evening off of a fork of iojs-no (which also has a new content directory) and the initial subtree was easy to get working in iojs/website off of the iojs/iojs-no/content directory.

BUT subsequent pulls/merges are tricky with this mechanism as git gets very confused. Dealing with the project root, or another branch's root, would be much easier. But I haven't given up :)

[snostorm]

Something like this flow worked, I think, but I'll confirm tomorrow:

Setup (from iojs/website)

git remote add -f snostorm_iojs-no git@github.com:snostorm/iojs-no.git
git merge --squash -s ours --no-commit snostorm_iojs-no/gh-pages
git read-tree -u snostorm_iojs-no/gh-pages:content
git commit -m "Subtree merged in snostorm_iojs-no/gh-pages"

Updating (from iojs/website)

git fetch snostorm_iojs-no
git diff-tree --relative=content -r -p \
snostorm_iojs-no/gh-pages content | git apply --directory=content/no

The diff-tree + apply approach was needed because we didn't fork from the repo base but instead a subfolder. The process may be a tad bit more simple / git party line / document using the remote branch's root.

Edit: this seems to not work for the 3rd commit. We may want to revisit the original idea of just using a second (clean) branch in iojs-no.

[therebelrobot]

On the agenda for Mar 2nd Website WG meeting #240

[Starefossen]

@snostorm the Norwegian translation is now available as a website branch on the iojs/iojs-no repo.

[snostorm]

git rm -fr content/no
git commit -m "Removes content/no to allow for subtree"

git remote add -f iojs-no git@github.com:iojs/iojs-no.git
git merge --squash -s ours --no-commit iojs-no/website
git read-tree --prefix=content/no/ -u iojs-no/website

git commit -m "Adds iojs-no content from iojs/iojs-no#website"

Successfully brought in content. Going to test a bit more from a fork of iojs/iojs-no#website to make sure edits work smoothly.

You're welcome to follow https://github.com/iojs/website/compare/iojs-no_website_subtree?expand=1 (so long as the branch exists.)

[snostorm]

To update / create a PR with new changes from iojs/website (either from the real branch or your own fork):

git fetch iojs-no website
git pull --squash -s subtree iojs-no website
git commit -m "Updats iojs-no content from iojs/iojs-no#website"

For this example I actually pulled from snostorm/iojs-no#website as I needed new commits to work against.

Technically, without --squash the final step isn't necessary, but it does keep the history easier to follow. (Less noise in the website repo.)

Note: this assumes you've locally run git remote add -f iojs-no git@github.com:iojs/iojs-no.git otherwise you'd need to refer to a non-aliased git path or your own local reference.

[snostorm]

Promoted that branch to a real PR -- #256. I'll be interested to see this merged then somebody in iojs-no create yet another small PR change against it (using the update steps I listed in the last message.)

[snostorm]

That PR is merged. True test will come when we have yet another PR on this folder.