Technical Tutorial on Setting Up a New Language

For the purposes of this tutorial, we assume the new language is Portuguese, with the ISO 639-1 2-letter language code PT

Create new defaults in _config.yml

You must add three new scope entries:

1. the entire pt directory
2. the pt "lessons" directory (updated as needed to match to the directory name as eventually translated by the PT team)
3. the pt "retired lessons" directory (updated as needed to match to the directory name as eventually translated by the PT team)

defaults:
  - scope:
      path: "pt"
    values:
      lang: "pt"
  - scope:
      path: "pt/licoes"
    values:
      lesson: true
  - scope:
      path: "pt/licoes/retirado"
    values:
      lesson: false
      retired: true

Temporarily exclude the new directory from the build process

In _config.yml we want to temporarily exclude these pages from being built:

exclude:
  - deprecated
  - vendor
  - Gemfile
  - Gemfile.lock
  - archive
  - pt

We will remove this exclusion when it is time to publish.

Add new language line to all snippets

In snippets.yml every entry needs to have a new line added with pt:. As needed, follow the pattern you see in existing snippets, such as the unique pattern used for the menu links:

# top nav bar
menu-home:
  en: /
  es: /es
  fr: /fr
  pt: /pt
menu-about:
    en: About
    es: Acerca
    fr: À propos
    pt:
menu-about-overview:
  en:
    title: About PH
    link: /en/about
  es:
    title: Acerca
    link: /es/acerca-de
  fr:
    title: À propos
    link: /fr/apropos
  pt:
    title:
    link:

As with all YAML, you must be exact about whitespace. After making all these changes, I strongly recommend trying a test build locally to see if you have any YAML errors here before moving on.

Note: Do NOT add the new language to language-list at the top of the file until you are ready to publish

Copy core pages to the new language directory

Create a new directory /pt and copy in the core pages from the /en folder, not including the lessons directory.

Make the following edits to each file:

1. Remove any extra YAML fields like redirect_only (these are needed to maintain our old URLs from prior to our multilingual restructuring). The only fields that you should keep are:
   • title
   • layout
   • skip_validation (if present)
   • skip_concordance (if present)
2. Add the original field to each page, and set it to the English base filename (so about.md should have original: about)

Create a directory for lessons and retired lessons, and add an empty file in the retired folder called .keep which will make sure the new folders get commited. For PT, we created the directory structure: /pt/licoes/retirado/.keep. (If the PT team decides to change those directory names, make sure to change the entries in _config.yml to match their decisions.

Create language logo and set theme color

Once the language team has settled on a logo variant and a theme color, add the hexadecimal color code to snippets.yml under background_color

Using that same color, go to the "ProgrammingHistorian logos" folder on the [email protected] Google drive and make new copies of the source files, the logo with and without the URL.

1. Adjust the filenames to match the naming convention of the other files
2. Adjust the color, URL, and logo typography as needed
3. Download the new files as SVG and save them in /images/logos

Add the new language to the RSS feed XML

Edit /feed.xml and add ensure the new languages are included:

{% assign pages = site.pages | where:'layout','lesson'|  where:'lang', 'pt' | sort:'translation_date' | reverse %}
{% for page in pages limit:10 %}
    {% include feed-item.html %}
{% endfor %}

Make pages public

1. Add the language abbreviation to available_languages
2. Edit _config.yml to remove the new language directory from the "excluded" paths. This means Jekyll will now attempt to build it.
3. Ensure that all checks pass.