Discuss: Internationalization of uPortal Documentation

[Christian Murphy]

Hey all,

Following up on conversations at Open Apereo about internationalizing the uPortal documentation. https://apereo.slack.com/archives/C0MNUQDN3/p1496687580648700

I found a tool which could help aid in the translation process, GitLocalize. https://gitlocalize.com/

GitLocalize reads in documentation from a source language folder, the offers a side by side editor for translating documentation, as well as tracking for how up-to-date translated versions are in reference to the source document.

GitLocalize integrates with Git SCM and GitHub to synchronize and update documentation.

I've opened a proof of concept pull request. https://github.com/Jasig/uPortal/pull/974

The pull request includes a tutorial, as well as changes to the documentation structure to prepare it for translation.

Feedback on this approach or tips on alternative approaches are welcome and appreciated.

Best Regards,

Christian Murphy

[Andrew Petro]

Can we start somewhere smaller first to work out the proof-of-concept?  Say, the uPortal-start repo, where the documentation is newer and smaller and kind of just being born so it's a fine time to try a new way to do it?

[Aaron Grant]

+1 good idea.

--
You received this message because you are subscribed to the Google Groups "uPortal Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to uportal-dev+unsubscribe@apereo.org.
Visit this group at https://groups.google.com/a/apereo.org/group/uportal-dev/.

--

Aaron Grant
Senior Applications Architect
Oakland University - UTS

[Christian Murphy]

Thanks for the feedback on the mailing list, on Slack, and on the PR itself!

Summary of feedback:

There is a lot of interest in localizing uPortal documentation.

There is consensus that uPortal documentation should be localized.

However uPortal's docs/ folder may be too large of a starting point.

Based off that feedback, I'm going to close out https://github.com/Jasig/uPortal/pull/974.

Currently none of the portlets nor uPortal-start have a documentation setup that would be able to support GitLocalize.

But as more documentation is ported into Github that should change and using GitLocalize could be revisited (It may be a while).

In the mean time, I'd be interested in getting more feedback, this time your thoughts on:

1. Are there tools or techniques would be more amenable?
   
2. What would constitute a successful outcome and a failure outcome for a PoC?
   
3. What would be an acceptable balance on documentation size, between docs small enough for a PoC to not disrupt documentation work, and large enough to verify the concept?

Best Regards,

Christian Murphy

On Thursday, August 10, 2017 at 10:30:54 AM UTC-7, asgrant wrote:

+1 good idea.

On Thu, Aug 10, 2017 at 1:16 PM, Andrew Petro <andrew...@wisc.edu> wrote:

Can we start somewhere smaller first to work out the proof-of-concept?  Say, the uPortal-start repo, where the documentation is newer and smaller and kind of just being born so it's a fine time to try a new way to do it?

On Friday, August 4, 2017 at 10:27:48 AM UTC-5, Christian Murphy wrote:

Hey all,

Following up on conversations at Open Apereo about internationalizing the uPortal documentation. https://apereo.slack.com/archives/C0MNUQDN3/p1496687580648700

I found a tool which could help aid in the translation process, GitLocalize. https://gitlocalize.com/

GitLocalize reads in documentation from a source language folder, the offers a side by side editor for translating documentation, as well as tracking for how up-to-date translated versions are in reference to the source document.

GitLocalize integrates with Git SCM and GitHub to synchronize and update documentation.

I've opened a proof of concept pull request. https://github.com/Jasig/uPortal/pull/974

The pull request includes a tutorial, as well as changes to the documentation structure to prepare it for translation.

Feedback on this approach or tips on alternative approaches are welcome and appreciated.

Best Regards,

Christian Murphy

--
You received this message because you are subscribed to the Google Groups "uPortal Developers" group.

To unsubscribe from this group and stop receiving emails from it, send an email to uportal-dev...@apereo.org.

Visit this group at https://groups.google.com/a/apereo.org/group/uportal-dev/.