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 a tracking issue for technical tasks related to starting the language team:

This is a tracking ticket for [technical tasks related to starting the $$$ team](https://github.com/programminghistorian/jekyll/wiki/Technical-Tutorial-on-Setting-Up-a-New-Language).

- [ ] Create new defaults in _config.yml 
- [ ] Add new language line to all snippets
- [ ] Copy core pages to the new language directory
- [ ] Push core pages to gh-pages branch so language team can begin translation
- [ ] Create language logo and set theme color
- [ ] Update CSS to include new colors
- [ ] Add the new language to the RSS feed XML
- [ ] Enable full text search stemming support
- [ ] Add the new team to [this](https://github.com/programminghistorian/jekyll/blob/15f818d6d11d9cee17f17e1689655b294d69397d/_includes/project-team-loop.html#L28) loop once editors have been added to the team's data files.
- [ ] Create Favicon
- [ ] Request DOIs from provider for new language
- [ ] Make pages public
- [ ] Open an issue for adding it to the Twitter bot when you reach a lesson threshold (usually seven lessons)

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.

Push core pages to gh-pages branch so language team can begin translation

Once the previous changes are done, the translation team can begin to work on translating and renaming pages to their language. They may submit PRs and merge them to gh-pages during this phase without affecting the public site, so not every single page needs to be translated and added in a single PR. All pages must be translated and merged to gh-pages before the final step where the pages are made public, however.

---

The following changes can happen while translation is going on:

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

Update CSS to include new colors

In css/style.css, in the block starting at line 56 you need to set the background color for the new language, like so:

.pt-back { background-color: {{ site.data.snippets.background_color.pt }}; }

Ensure the new language to the RSS feed XML

We recently updated the RSS feed to add new language material automatically. Check /feed.xml on the site preview to ensure the new language's material appears. If not, you'll need to edit the logic in /feed.xml

Enable full text search stemming support

A dedicated lunr language stemmer needs to be added to the /js/vendor directory. Work with the technical team and consult the Technical Tutorial on Search for this step.

---

Create favicon

In /images/favicons/ create a .ico file with the format LANGABBREV_favicon.ico. You'll want to take the logo file from /images/logos/ and use photoshop to create one in the same format as the others.

---

Request DOIs for new language from provider

Ask @drjwbaker (or someone else on ProgHist Ltd) on behalf of the Ltd to check with the DOI provider that they are happy provide DOIs for a new publication. If the provider cannot supply DOIs the new publication will run without DOIs until the Ltd finds a solution

---

FINALLY: Make pages public

1. Add the language abbreviation to language-list in snippets.yml
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. The first full build you try will probably have errors, particularly with incorrect links between the core pages! Be patient and read the errors carefully. Try to do this step locally first to clean up most major errors before opening up the pull request.

A Note on Testing

In order to actually troubleshoot the new translated pages as they come in, you will want to:

• Run the site locally.
• Make sure that pages you are looking at do not have 'skip_validation: true' in the YML.
• Temporarily make the site appear as part of the project. This means adding the language abbreviation to 'language-list' in snippets.yml and editing the '_config.yml' file so that it is not excluded from building. Important: this means the site will be built and displayed. You need to remember to undo these steps before pushing anything, or else you will have a half-built language site as part of the main, live project.
• Check the terminal for validation errors
• Click through the pages for any obvious syntax issues. Might be easier to just type the URLs in directly.
• Report back
• Repeat

Note that you can merge in portions of the site and not worry about affecting the site as a whole. None of that material will be public until you take steps under "FINALLY: Make pages public."