Add translations to the main site (+markdown transition) [DON'T MERGE] #621

2018-11-25T19:44:39Z

ghost commented

2018-11-25 19:44:39 +00:00

(Migrated from github.com)

We will slowly transition from HTML to Markdown, wherever practical. This will result in much more readable and newbie-friendly files.

The first commit in this branch shows how we will implement localization. The main site will be multilingual -- this doesn't mean that the forks can't have their own repos and domains. It will be much easier for them to keep up, due to the utilization of ~~JSON~~ YAML language files.

We will slowly transition from HTML to Markdown, wherever practical. This will result in much more readable and newbie-friendly files. The first commit in this branch shows how we will implement localization. The main site will be multilingual -- this doesn't mean that the forks can't have their own repos and domains. It will be much easier for them to keep up, due to the utilization of <strike>JSON</strike> YAML language files.

ghost commented

2018-11-29 15:55:48 +00:00

(Migrated from github.com)

We'll use yaml ~~instead of JSON to avoid painful escaping of ".~~
- This is all you need to know:
  - yaml files start and end with a line of ---
  - single-line string: key: value
  - multi-line string:
```
key: >
     value
```
For some complex parts, we'll use HTML. Such as the nothing to hide quote. Other sections can be converted into markdown.
Inside index.html, you use localized strings like this:
```
{{ language.key | default: english.key }}
{{ language['key'] | default: english['key']
```
- The variable names are different from includes, because including something in index.html would override the variables.
- These variables will be used for strings not related to sections but to index.html in general.
index.html is now in _includes
Files in languages/ include index.html and set the language for it.

Files in _includes/langs/ look like this:

{% assign title = include.lang.title | default: include.en.title %}
{% assign quote = include.lang.quote | default: include.en.quote %}
{% assign talk_name = include.lang.talk_name | default: include.en.talk_name %}

This allows for using {{ title }} instead of {{ lang.title | default: en.title }} in the md files (or the index.html file, depending on how we decide. See below.).

I am not sure about this, but likely we'll do it this way:

The files with content are stored in _include/content
- They start with
```
{% assign lang = site.data.lang.[include.lang].<<filename>> %}
{% assign en = site.data.lang.en.<<filename>> %}
```
  - <<filename>> being the name of the file without the extension

index.html will be full of content includes, but the advantage is that we'll have far less conflicts.

- We'll use yaml <strike>instead of JSON to avoid painful escaping of `"`.</strike> - This is all you need to know: - yaml files start and end with a line of `---` - single-line string: `key: value` - multi-line string: ```yaml key: > value ``` - For some complex parts, we'll use HTML. Such as the nothing to hide quote. Other sections can be converted into markdown. - Inside `index.html`, you use localized strings like this: ```liquid {{ language.key | default: english.key }} {{ language['key'] | default: english['key'] ``` - The variable names are different from includes, because including something in `index.html` would override the variables. - These variables will be used for strings not related to sections but to index.html in general. - `index.html` is now in `_includes` - Files in `languages/` include `index.html` and set the language for it. - Files in `_includes/langs/` look like this: ```liquid {% assign title = include.lang.title | default: include.en.title %} {% assign quote = include.lang.quote | default: include.en.quote %} {% assign talk_name = include.lang.talk_name | default: include.en.talk_name %} ``` This allows for using {{ title }} instead of {{ lang.title | default: en.title }} in the md files (or the index.html file, depending on how we decide. See below.). I am not sure about this, but likely we'll do it this way: - The files with content are stored in `_include/content` - They start with ```liquid {% assign lang = site.data.lang.[include.lang].<<filename>> %} {% assign en = site.data.lang.en.<<filename>> %} ``` - `<<filename>>` being the name of the file without the extension index.html will be full of content includes, but the advantage is that we'll have far less conflicts.

ghost commented

2018-12-15 16:35:38 +00:00

(Migrated from github.com)

I haven't yet decided what all will be converted into markdown.

It would be cool if we could convert

# headings

into headings with an anchor link and a FA link icon.

I guess moving the VPN comparison table to a separate file will be great, as index.html will be far less bloated.

The navigation thing on the right shows how big the VPN comparison table is.

Things like

<h3>Related Information</h3>
<ul>
    <li><a href="https://www.bestvpn.com/the-ultimate-privacy-guide/#avoidus">Avoid all US and UK based services</a></li>
    <li><a href="https://en.wikipedia.org/wiki/Surespot#History">Proof that warrant canaries work based on the surespot example.</a></li>
    <li><a href="http://en.wikipedia.org/wiki/UKUSA_Agreement">http://en.wikipedia.org/wiki/UKUSA_Agreement</a></li>
    <li><a href="http://en.wikipedia.org/wiki/Lavabit#Suspension_and_gag_order">http://en.wikipedia.org/wiki/Lavabit#Suspension_and_gag_order</a></li>
    <li><a href="https://en.wikipedia.org/wiki/Key_disclosure_law">https://en.wikipedia.org/wiki/Key_disclosure_law</a></li>
    <li><a href="http://en.wikipedia.org/wiki/Portal:Mass_surveillance">http://en.wikipedia.org/wiki/Portal:Mass_surveillance</a></li>
</ul>

Can be converted into markdown easily and it will be a great thing.

I guess this could be converted nicely into markdown, though I'm not sure about img-fluid float-right.

It's important to keep in mind that we can freely use HTML in MD. At least on GitHub. Seems to be that way for most MD compilers. So this will likely be true in Jekyll/Liquid as well.

Will we move these sections to separate files too?

@Vincevrp

I haven't yet decided what all will be converted into markdown. It would be cool if we could convert `# headings` into headings with an anchor link and a FA link icon. I guess moving the VPN comparison table to a separate file will be great, as index.html will be far less bloated. ![screenshot from 2018-12-15 17-28-35](https://user-images.githubusercontent.com/4354706/50045197-e773e900-008e-11e9-8483-6642f6f1d0e4.png) The navigation thing on the right shows how big the VPN comparison table is. --- Things like ```html <h3>Related Information</h3> <ul> <li><a href="https://www.bestvpn.com/the-ultimate-privacy-guide/#avoidus">Avoid all US and UK based services</a></li> <li><a href="https://en.wikipedia.org/wiki/Surespot#History">Proof that warrant canaries work based on the surespot example.</a></li> <li><a href="http://en.wikipedia.org/wiki/UKUSA_Agreement">http://en.wikipedia.org/wiki/UKUSA_Agreement</a></li> <li><a href="http://en.wikipedia.org/wiki/Lavabit#Suspension_and_gag_order">http://en.wikipedia.org/wiki/Lavabit#Suspension_and_gag_order</a></li> <li><a href="https://en.wikipedia.org/wiki/Key_disclosure_law">https://en.wikipedia.org/wiki/Key_disclosure_law</a></li> <li><a href="http://en.wikipedia.org/wiki/Portal:Mass_surveillance">http://en.wikipedia.org/wiki/Portal:Mass_surveillance</a></li> </ul> ``` Can be converted into markdown easily and it will be a great thing. I guess this could be converted nicely into markdown, though I'm not sure about `img-fluid float-right`. ![screenshot from 2018-12-15 17-30-30](https://user-images.githubusercontent.com/4354706/50045219-36218300-008f-11e9-8436-6d933ca0fe3f.png) It's important to keep in mind that we can freely use HTML in MD. At least on GitHub. Seems to be that way for most MD compilers. So this will likely be true in Jekyll/Liquid as well. --- Will we move these sections to separate files too? ![screenshot from 2018-12-15 17-34-42](https://user-images.githubusercontent.com/4354706/50045253-c19b1400-008f-11e9-8ba2-e0ce535285bc.png) @Vincevrp

jonah reviewed

2018-12-23 20:21:59 +00:00

jonah left a comment

https://github.com/privacytoolsIO/privacytools.io/pull/621/commits/38954bc3631f66eab1cd1d9c42359ea8f499b8b7

Activist:

A tool to make working with localized sections easier.

Inspired by Laravel's artisan.

The created file in content/ starts with

{% include section_config section=include.section lang=include.lang %}

https://github.com/privacytoolsIO/privacytools.io/pull/621/commits/38954bc3631f66eab1cd1d9c42359ea8f499b8b7 ### Activist: > #### A tool to make working with localized sections easier. > > Inspired by Laravel's artisan. ![peek 2018-12-23 21-20](https://user-images.githubusercontent.com/4354706/50387285-b3d13880-06f8-11e9-96c7-5a7567d4cf2d.gif) The created file in `content/` starts with {% include section_config section=include.section lang=include.lang %} ![peek 2018-12-23 21-30](https://user-images.githubusercontent.com/4354706/50387348-05c68e00-06fa-11e9-9e39-0d75d41ef2e2.gif)

c0rdis commented

2018-12-29 10:05:06 +00:00

(Migrated from github.com)

@Shifterovich what do you think of adding icons to the header template as they are now present at https://privacytools.ru? Also, I've made some re-ordering of the sections (and actually added a couple, which are only relevant to RU - so probably we should consider "floating sections"), so if you believe it makes sense, I can help with both things on the main template.

ghost commented

2018-12-29 10:10:52 +00:00

(Migrated from github.com)

Good idea, that might for now solve the issue with the messy navbar. It will be easier to navigate in it.

BTW, after discussing this with @Vincevrp we came across two things:

Both YAML and translated markdown files are a trade-off. Simply splitting the website into .md files per sections isn't.
Maintaining the translations would mean that most pull requests would be related to translations. It's a better idea to split index into markdown files, making it easier for forks to stay up to date (with less conflicts etc).

So we will simply split index.html into markdown files by sections.

Good idea, that might for now solve the issue with the messy navbar. It will be easier to navigate in it. BTW, after discussing this with @Vincevrp we came across two things: - Both YAML and translated markdown files are a trade-off. Simply splitting the website into .md files per sections isn't. - Maintaining the translations would mean that most pull requests would be related to translations. It's a better idea to split index into markdown files, making it easier for forks to stay up to date (with less conflicts etc). So we will simply split index.html into markdown files by sections.

👍 2

Vincevrp commented

2019-01-20 17:53:17 +00:00

(Migrated from github.com)

Closing in favour of #730.

This repo is archived. You cannot comment on pull requests.

1 Participants

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: privacyguides/privacytools.io#621