[POC] UP-4917: GitLocalize setup

[ChristianMurphy]

Checklist

• the individual contributor license agreement is signed
• commit message follows commit guidelines
• documentation is changed or added
• message properties have been updated with new phrases

Description of change

Jira: https://issues.jasig.org/browse/UP-4917
Mailing list: https://groups.google.com/a/apereo.org/d/topic/uportal-dev/Jh5emWPXnHA/discussion
Slack: https://apereo.slack.com/archives/C0MNUQDN3/p1496687580648700

⚠️ Proof of Concept ⚠️
This is designed to spark discussion on what approach to take when localizing uPortal documentation.
It may or may not be the best approach.

ℹ️ About GitLocalize

Git Localize is tool that provides a WYSIWYG editor for translating documentation, along with documentation completeness tracking, and deep integration with GitHub version control.

📽️ GitLocalize Tutorial

🚧 Changes in this pull request

This pull request restructures the documentation folder to have a different sub-folder for each supported language.
Starting with English, and growing as each additional language starts to be translated.

[bjagg]

Looks very promising. I would prefer an English version of the README with links to the other translations as the first section. Rest of the English docs could be in a subfolder.

[ChristianMurphy]

Hey @bjagg,
That could be done, I like the idea of reducing the number of click to get to content, which appears to be your intent.
Moving the README linking to all the subdocuments out of docs/en would mean that GitLocalize would not pick up that the document should be localized.

An alternative could be, adding the assumption that English is the default language.
Automatically redirecting https://jasig.github.io/uPortal/ to https://jasig.github.io/uPortal/en.
And moving the language selection (currently in /docs/README.md) to the localized README docs/en/README.md.

Would the alternative resolve your concerns? Or would you still prefer the README to move? 💭

[bjagg]

@ChristianMurphy I think we can assume English as the default (for now) and add the redirect. As long as it is quickly obvious we have other translations.

[ChristianMurphy]

@bjagg updated.
You can see how the redirect will behave by trying this link https://christianmurphy.github.io/uPortal/

[asgrant]

@ChristianMurphy I noticed the french docs were 404ing. Also this mirrors some conversations I had with @cousquer at the Apereo conference, I think this is a good idea.

[ChristianMurphy]

I noticed the french docs were 404ing

@asgrant that is correct.
This adds the structure for where documentation will go 🔜
It has not yet added any of the documents in French 🇫🇷

For demo purposes, I used Google translate + GitLocalize to create /docs/fr/index.md ChristianMurphy#3.

https://christianmurphy.github.io/uPortal/fr/

[gcarroll]

Couldn't this read from the build environment default language? I am not certain what this would entail and thought I would comment given that this is intended to be for commenting. Just an idea.

[ChristianMurphy]

@gcarroll I like the idea of directing users to the appropriate language based off some identifier. 👍
The official uPortal 5 docs are built and hosted on GitHub servers, if the build environment was used as the identifier, the language would always be set English. 🇬🇧 🇺🇸
The uPortal docs can be hosted outside of GitHub, but are not intended to be currently.

However if it was managed using JavaScript on the client side. 🤔
The web browser navigator.language attribute could be used to redirect to an appropriate page. ⏭️

The some challenges to a client side approach would be:

• it would require JavaScript to be enabled.
• some browser addon/plugins mess with the Navigator object, making the data unreadable or unusable.
• It would require two lists of languages to be kept, one human readable in index.md, another machine readable in JavaScript.

[gcarroll]

@ChristianMurphy per your reply I did a quick search and found this: https://github.com/github/linguist this might be the key or possibly the building block. I really should get back on track with my implementation. I have a lot going on which is partly why I have been lurking rather then actively participating. I am in two worlds as my uPortal build is on a remote Linux server and my access to that server is from ssh via Windows 10. I am currently grappling with implementation of CAS which is outside this topic. Perhaps someone else has some input?

[ChristianMurphy]

Thanks @gcarroll!

I did a quick search and found this: https://github.com/github/linguist this might be the key or possibly the building block.

Tools like linguist and franc can identify the language of files based off their contents.
What are your thoughts on how that would be used? 💭

I really should get back on track with my implementation. I have a lot going on

No worries.
If you have any questions, feel free to reach out to @uportal-user.

I am currently grappling with implementation of CAS which is outside this topic.

CAS also has an active mail group that can help with questions @cas-user.

[ChristianMurphy]

Based on feedback from mailing list, this will need to be tested on a smaller documentation set.
Closing this PR out.