Re: Documentation pages

[Chris Holmes]

Hey, switching this to the public lists.

Do we have sync working on the translations? I don't see any of them showing up at all - like if I change to spanish in the dropdown I don't see anything. And I don't see spanish in https://github.com/getlantern/lantern-docs/tree/master/lantern

And Todd, did you get it working the other way? Like updates from lantern-docs going in to transifex? 

It shouldn't be hard to put out a call to encourage translators for the docs, we just have to message them on transifex.

But we should make sure that their experience translating will be good - that after translating in transifex they should see their work show up on the website.

The other thing we need to figure out is how to handle screenshots.

On Wed, Jun 11, 2014 at 3:41 PM, Todd Blose <to...@getlantern.org> wrote:

Cool. I added some separators: http://107.170.244.214/docs/Switching-Google-Accounts.html

On 6/11/14, 2:46 PM, Adam Fisk wrote:

Yeah exactly on the mongodb front -- just something that offsets it a bit.

On Wed, Jun 11, 2014 at 2:34 PM, Todd Blose <to...@getlantern.org> wrote:

I can add some further styling while I'm doing this. I just didn't really
have any design to base it off of and improvised. Do you mean separators
similar to the mongo docs I just sent, or can you point me to a good
reference you would want it to more closely resemble?

Also, there's a full-text search on the documentation which I think will be
useful:
http://107.170.244.214/docs/search.html?q=proxy&check_keywords=yes&area=default
-- it should work in multiple languages too. Let me run a test once I fix
the formatting issue toggling between languages.



On 6/11/14, 2:25 PM, Adam Fisk wrote:

Nice. Yeah I think the side menu works well. It in theory could use a
little styling, like maybe a little separator or something, but I say
we go with this and revisit later!

On Wed, Jun 11, 2014 at 2:13 PM, Todd Blose <to...@getlantern.org> wrote:

Oh, that's totally breaking. Thanks for pointing that out. Let me fix it.
Yeah, most of the documentation (categorized as "Documentation" on our
account page here:
https://www.transifex.com/projects/p/lantern/resources/),
and it looks like only French/Spanish are the languages significantly
translated so far. None of the documentation has been translated yet in
Farsi.

The side menu looks good though? I'm almost done making it fully
responsive
similar to here: http://docs.mongodb.org/manual/ so it should look nice
on
smaller screens shortly.

Thanks,
Todd


On 6/11/14, 2:04 PM, Adam Fisk wrote:

Great Todd. Looking very close. The only other issue I noticed is
left-to-right languages. It looks like the TOC gets messed up
switching to Farsi, for example, although I suppose the larger issue
with Farsi at the moment is complete lack of translation of the docs
at all, is that right?

On Tue, Jun 10, 2014 at 8:44 PM, Todd Blose <to...@getlantern.org> wrote:

The docs section of the site has a side-menu, search section, and
improved
styling now: http://107.170.244.214/docs/Using-Lantern.html

I think the biggest remaining issue is the side menu being responsive.
It's
breaking right now on smaller mobile screens. That's about the only
thing
I've noticed so far, and I'm going to continue making small
improvements
this evening. Let me know how it looks and if you see any other
discrepancies!

Thanks,
Todd

[Todd Blose]

Hey Chris,

Responses inline.

On 6/12/14, 6:31 PM, Chris Holmes wrote:

Hey, switching this to the public lists.

Do we have sync working on the translations? I don't see any of them showing up at all - like if I change to spanish in the dropdown I don't see anything. And I don't see spanish in https://github.com/getlantern/lantern-docs/tree/master/lantern

The translations are hooked up with Transifex here: https://github.com/getlantern/lantern-docs/tree/master/translations

I've been using the transifex-client to synchronize changes, and the process is outlined here:
http://support.transifex.com/customer/portal/topics/440187-transifex-client/articles

Here's how your ~/.transifexrc file should look
[https://www.transifex.com/projects/p/lantern/]
hostname = https://www.transifex.com
username = <username>
password = <password>
token =

The README contains instructions on what packages are needed-- https://github.com/getlantern/lantern-docs

and there's a more detailed run-through here: http://fedoraproject.org/wiki/Setting_up_a_document_with_Transifex#Step_4:_Initialize_Transifex_in_Your_Git_Repository

And Todd, did you get it working the other way? Like updates from lantern-docs going in to transifex?

For this, I think it makes sense for us to consolidate the new resources I created with the existing Key-Value JSON strings here: https://www.transifex.com/projects/p/lantern/resource/www/ that the rest of the site is already using; AngularJS can then substitute strings between languages on any documentation page trivially, and we don't have to rely on sphinx to generate different directories for every language. We also don't have to worry then about maintaining documentation pages per language, and it's better user experience seeing the substitutions happen without any re-direction necessary.

You can see this working here: http://107.170.244.214/docs/Lantern-Cloud-Servers.html#es (try toggling between English/Spanish/French).

The only caveat with this has been tediously migrating the existing translation work done to new key-value pairs. I've been spending the night adding most of these and should have the rest ready for tomorrow. The biggest hold-up: angular (sometimes) refuses to translate bindings that contain HTML, but I think I've found a workaround for that discussed here: http://stackoverflow.com/questions/19754381/how-to-handle-strings-containing-html-using-angular-translate

It shouldn't be hard to put out a call to encourage translators for the docs, we just have to message them on transifex.

But we should make sure that their experience translating will be good - that after translating in transifex they should see their work show up on the website.

Agreed. That's why I think keeping key-value pairs will result in the best experience. I also fixed the styling when we convert to Farsi http://107.170.244.214/docs/Lantern-Cloud-Servers.html#fa_IR (is there a specific reason we're doing this weird reflection though?). I also received multiple translations I'm going to add strings for. Once we push everything back to Transifex, it should preserve all the existing work and make it easy synchronizing changes moving forward.

The other thing we need to figure out is how to handle screenshots.

This should be solved now that we're doing string substitution everywhere. We can re-create the screenshots in whatever language and just swap out images based on the language selected.

Let me know how this all sounds!

Thanks,
Todd

[Todd Blose]

It looks like the new version of angular-translate handles strings containing HTML just fine now. I upgraded it and angular as well. We can now do

<p translate="{{ 'PASSED_AS_INTERPOLATION' }}"></p> 

instead of

<p ng-html-bind="{{ 'PASSED_AS_INTERPOLATION' | translate }}"></p> 

for string substitution now.

Thanks!
Todd