Draft: Internationalization for fortran-lang

Gemfile

@@ -3,5 +3,8 @@ source 'https://rubygems.org'
 # This will help ensure the proper Jekyll version is running.
 gem "jekyll", "~> 3.8.5"
 
+# I18n support for Jekyll
+gem "jekyll-multiple-languages-plugin"
+
 # https://github.com/github/pages-gem
 #gem 'github-pages', group: :jekyll_plugins

Gemfile.lock

@@ -27,6 +27,8 @@ GEM
       pathutil (~> 0.9)
       rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
+    jekyll-multiple-languages-plugin (1.7.0)
+      jekyll (>= 2.0, < 5.0)
     jekyll-sass-converter (1.5.2)
       sass (~> 3.4)
     jekyll-watch (2.2.1)
@@ -56,6 +58,7 @@ PLATFORMS
 
 DEPENDENCIES
   jekyll (~> 3.8.5)
+  jekyll-multiple-languages-plugin
 
 BUNDLED WITH
-   2.1.4
+   2.2.5

README.md

@@ -11,6 +11,9 @@ It's derived from https://github.com/neovim/neovim.github.io.
 
 * [PACKAGES](./PACKAGES.md): adding an entry to the [Package index](https://fortran-lang.org/packages)
 
+* [TRANSLATING](./TRANSLATING.md): details on how to translate the webpage in a new language
+
+
 ## Setup
 
 This assumes that you already have a recent Ruby with RubyGems.

TRANSLATING.md

@@ -0,0 +1,82 @@
+Translation and Internationalization
+====================================
+
+The fortran-lang.org webpage uses the
+[jekyll-multiple-languages-plugin](https://github.com/kurtsson/jekyll-multiple-languages-plugin)
+to support translations for multiple languages.
+The plugin provides three main functionalities to allow the localization of content:
+
+- `translate`, `t`:
+  replace expression with content from language file in ``_i18n/<lang>.yml`` file,
+  this functionality does not provide a fallback to the default language.
+  The translate function does not expand liquid templates.
+- `translate_file`, `tf`:
+  include file from ``_i18n/<lang>/`` subtree, this functionality automatically
+  falls back to the default language subtree if no translation is available.
+  Liquid templating is possible here like usual.
+- `translate_link`, `tl`
+  localization of permalinks is currently not used.
+
+The default behaviour of jekyll is mostly retained, new pages are added in the main
+subtree as usual. To provide the possibility to localize page content all English
+keywords or content blocks are included with ``{% t ... %}`` or ``{% tf ... %}`` in the
+main tree while the actual content is provided in the English subtree at ``_i18n/en/``.
+Therefore, it is best to have content and markup separated for all localized pages.
+
+The content of the language configuration file is available as ``site.translations[lang]``.
+Note that you cannot reliably access content of other language files by this mean.
+The ``site.baseurl`` variable is localized as well, to access the actual root, *e.g.*
+to get to the assets directory to include CSS use the ``site.baseurl_root`` variable instead.
+
+
+## Adding a new language.
+
+Before starting to translate, make sure to setup *jeykll* as described in the
+[README](./README.md).
+
+To add a new language to the webpage add the language name to the *languages* array
+in the [``_config.yml``](./_config.yml) file.
+The language name should be represented by its two letter code, the full name of the
+language will be provided in the localized configuration files at ``./_i18n/<lang>.yml``.
+The first language in the arrays is the default language and is used in the main tree
+at ``https://fortran-lang.org`` while additional trees are generated under
+``https://fortran-lang.org/<lang>``.
+You might have to restart *jekyll* to apply changes from the config file.
+
+Add the new language in the [``_data/langs.yml``](./_data/langs.yml) file together with
+its name, those entries will be used in the footer as navigation between the translations.
+
+
+### Translating keywords
+
+After adding a language to the config file, add its English name to the English subtree
+at [``_i18n/en.yml``](./_i18n/en.yml) to the *langs* field.
+To create a new tree from the added language copy the English language file
+
+```
+cp _i18n/en.yml _i18n/<lang>.yml
+```
+
+You can now start to fill the keyword translations in the new ``<lang>.yml`` file.
+Make sure to keep the same structure as in the English language file, since missing
+keywords will be dropped rather than filled in from the default language.
+
+
+### Translating content
+
+To translate the content of the main page create a copy of the included HTML or markdown
+files from the English subtree in the new language tree under ``_i18n/<lang>/``.
+Files that do not have a translation will be used from the default language automatically,
+therefore you can translate one file at a time.
+
+
+### Creating posts
+
+Posts are limited to their language scope, to include the posts from the English page
+the recommended strategy is to create symbolic links from the entries in
+``_i18n/en/_posts`` to the localized variant ``_i18n/<lang>/_posts`` instead of
+copying the complete posts.
+
+Note that this allows to have posts visible only in certain language subtrees, which
+can be useful if you want to announce local events or have translated versions of
+the English posts.

_config.yml

@@ -4,6 +4,7 @@ markdown: kramdown
 
 title: Fortran Programming Language
 description: "Fortran Programming Language"
+languages: ["en", "es", "fr"]
 
 news:
     name: Fortran Newsletter
@@ -13,7 +14,10 @@ news:
 
 url: "https://fortran-lang.org"
 
+exclude_from_localizations: ["assets"]
+
 plugins:
+  - jekyll-multiple-languages-plugin
 
 exclude:
     - CNAME

_data/langs.yml

@@ -0,0 +1,3 @@
+en: English
+es: Español
+fr: Français

_i18n/en.yml

@@ -0,0 +1,160 @@
+global:
+  title: Fortran Programming Language
+  description: "Fortran Programming Language"
+  discourse: Discourse
+  twitter: Twitter
+  github: GitHub
+  documentation: Documentation
+  contributing: Contributing
+  faq: FAQ
+  rss_feed: RSS feed
+  rss_client: >-
+    RSS clients can follow the
+    <a href="https://fortran-lang.org/news.xml" target="_blank">RSS feed</a>.
+  mailing_list: Mailing List
+  toggle_nav: Toggle navigation
+  site_preview: Site preview
+  site_preview_info: you are previewing unpublished changes for
+  pull_request: pull request
+  join_discourse: >-
+    Join the discussion about all things Fortran on the
+    <a href="https://fortran-lang.discourse.group" target="_blank">fortran-lang discourse.</a>
+  hosted_on_github: >-
+    This site's source is <a href="https://github.com/fortran-lang/fortran-lang.org/">hosted on GitHub</a>.
+  subscribe_to_mailing_list: >-
+    Subscribe to our <a href="https://groups.io/g/fortran-lang" target="_blank">mailing list</a>
+    to discuss anything Fortran related, announce Fortran projects, discuss development
+    of core fortran-lang.org projects (stdlib, fpm), and get
+    the latest news.
+
+page:
+  home:
+    title: Home
+  learn:
+    title: Learn Fortran
+    description: Learning resources for beginners and experts alike
+  news:
+    title: News
+    archive:
+      title: News archive
+  compilers:
+    title: Fortran Compilers
+  community:
+    title: Fortran-lang Community
+    description: Collaboration for the advancement of Fortran
+  packages:
+    title: Fortran Packages
+    description: A rich ecosystem of high-performance code
+    search:
+      title: Search
+    category:
+      data-types:
+        title: Data types and containers
+        description: Libraries for advanced data types and container classes
+      examples:
+        title: Examples and templates
+        description: Demonstration codes and templates for Fortran
+      fpm:
+        title: FPM Registry Packages
+        description: Packages listed in the fpm-registry
+      graphics:
+        title: Graphics, plotting and user interfaces
+        description: Libraries for plotting data, handling images and generating user interfaces
+      interfaces:
+        title: Interface libraries
+        description: Libraries that interface with other systems, languages, or devices
+      numerical:
+        title: Numerical projects
+        description: Fortran libraries for linear algebra, optimization, root-finding etc.
+      programming:
+        title: Programming utilities
+        description: Error handling, logging, documentation and testing
+      scientific:
+        title: Scientific Codes
+        description: Applications and libraries for applied mathematical and scientific problems
+      strings:
+        title: Characters and strings
+        description: Libraries for manipulating characters and strings
+      io:
+        title: Input, output and parsing
+        description: Libraries for reading, writing and parsing files and inputs
+      libraries:
+        title: Libraries
+        description: Fortran libraries for general programming tasks
+
+home:
+  tagline: High-performance parallel programming language
+  get_started: Get started
+  more: More
+  join_us: Join us!
+  make_fortran_better: Make Fortran better
+
+nav:
+- title: Learn
+  url: /learn/
+- title: Compilers
+  url: /compilers/
+- title: Community
+  url: /community/
+- title: Packages
+  url: /packages/
+- title: News
+  url: /news/
+
+nav_key:
+  home: Home
+  learn: Learn
+  compilers: Compilers
+  community: Community
+  packages: Packages
+  news: News
+
+learn:
+  getting_started: Getting started
+  quickstart_tutorial: Quickstart tutorial
+  fortran_lang_discourse: Fortran-lang Discourse
+  minibook_tutorials: Mini-book Tutorials
+  other_resources: Other Resources
+  on_the_web: On the web
+  in_print: In print
+
+book:
+  authors: Authors
+  introduction: Introduction
+  back_to_learn: Back to Learn Fortran index
+  important: Important
+  note: Note
+  tip: Tip
+
+book_nav:
+  back: Back
+  next: Next
+
+news:
+  archive: Archive
+  authors: Authors
+  back_to_news: Back to news
+  more: More
+  read_more: Read more
+
+packages:
+  featured: Featured Open Source Projects
+  tagline: A rich ecosystem of high-performance code
+  back: Back to all Packages
+  fpm_registry: FPM Registry
+  fpm_projects: >-
+    Projects compatible with the
+    <a href="https://github.com/fortran-lang/fpm" target="_blank">
+    Fortran Package Manager</a>
+  tags: Tags
+  author: Author
+  maintainer: Maintainer
+  find_a_package: Find a Package
+  featured_topics: Featured topics
+  browse: Browse Packages by Category
+  search_for_a_project: Search for a project
+  search_for_a_package: Search for a package
+
+community:
+  header: Fortran-lang Community Projects
+  get_involved: Get Involved

_i18n/en/community/build_and_test.html

@@ -0,0 +1,9 @@
+<h3> <i data-feather="terminal"></i>
+  Build and Test</h3>
+<p>
+Get more involved with each project by cloning, building and testing
+it on your own machine(s) and with your own codes;
+if something doesn't work, create an issue to let us know!
+We value user feedback highly, be it a bug report, feature request, or
+suggestion for documentation.
+</p>

_i18n/en/community/community_conduct.html

@@ -0,0 +1,10 @@
+<h3><i data-feather="smile"></i>
+  Community Conduct</h3>
+<p>
+As a community, we strive to make participation in our discussions and projects a friendly and
+harassment-free experience for everyone.
+
+</p>
+<p> See the full
+<a href="https://github.com/fortran-lang/stdlib/blob/master/CODE_OF_CONDUCT.md" target="_blank" rel="noopener">Code of Conduct</a>
+</p>

_i18n/en/community/contributor_guide.html

@@ -0,0 +1,12 @@
+<h3> <i data-feather="edit"></i>
+  Contributor Guide</h3>
+<p>
+Want to contribute code and content?
+Check out the contributor guides in each repository for information
+on the project workflow and recommended practices.
+</p>
+<ul>
+  <li> <a href="https://github.com/fortran-lang/stdlib/blob/master/WORKFLOW.md" target="_blank" rel="noopener">Contributor guide for stdlib</a> </li>
+  <li> <a href="https://github.com/fortran-lang/fpm/blob/master/CONTRIBUTING.md" target="_blank" rel="noopener">Contributor guide for fpm</a> </li>
+  <li> <a href="https://github.com/fortran-lang/fortran-lang.org/blob/master/CONTRIBUTING.md" target="_blank" rel="noopener">Contributor guide for fortran-lang.org</a> </li>
+</ul>

_i18n/en/community/fortran_lang_contributors.html

@@ -0,0 +1,4 @@
+<h2>Fortran-lang Contributors</h2>
+<p>
+We are grateful for every contribution made by all members of the community.
+</p>

_i18n/en/community/fpm.html

@@ -0,0 +1,6 @@
+<h3><i data-feather="package"></i>
+  Fortran Package Manager (fpm)</h3>
+<p>
+A prototype project to develop a common build system for Fortran packages
+and their dependencies.
+</p>

_i18n/en/community/join_the_discussion.html

@@ -0,0 +1,14 @@
+<h3>
+  <i data-feather="message-circle"></i>
+  Join the Discussion</h3>
+<p>
+The easiest way to join the community and contribute is by
+commenting on issues and pull requests in the project
+repositories.
+<!-- Open discussion is vital to making project decisions,
+  and benefits greatly from varied expertise and insight across the community. -->
+  Whether Fortran beginner or seasoned veteran, your feedback and comments are most
+  welcome in guiding the future of Fortran-lang.
+
+
+</p>

_i18n/en/community/stdlib.html

@@ -0,0 +1,7 @@
+<h3><i data-feather="database"></i>
+   Fortran Standard Library (stdlib)</h3>
+<p>
+A community-driven project for a <i>de facto</i> "standard" library for Fortran.
+The stdlib project is both a specification and a reference implementation, developed in
+cooperation with the Fortran Standards Committee.
+</p>

_i18n/en/community/website.html

@@ -0,0 +1,5 @@
+<h3><i data-feather="globe"></i>
+  fortran-lang.org</h3>
+<p>
+This website is open source and contributions are welcome!
+</p>