Tutorial: Front page text configuration
This tutorial will describe how to use some configuration options for the frontpage of your Open SDG implementation. This is intended to be a continuation of the quick start tutorial.
Topics covered¶
- Site configuration
- Custom translations
Note that this tutorial involves translation, and assumes that your Open SDG implementation is using the two languages included in the Quick Start: English and Spanish. If you have already added/removed languages, then when you see mentions of languages later in this tutorial, you may need to interpret accordingly.
Level of difficulty¶
This tutorial involves working with text files, but requires no previous technical expertise.
Customize some text on the frontpage¶
Take a look at the frontpage of your Open SDG implementation (if you have not already done so, complete the quick start tutorial). Notice how, above the grid of goal icons, it says:
Our data for Sustainable Development Goal indicators
In this tutorial you are going to customize that text to better suit your implementation. The steps are as follows:
- Log in to Github.com, and go to your site repository.
- In the list of files, click into the
_data
folder and click onsite_config.yml
. Alternatively, you can alter this setting using the site configuration form. If you do not have the_data
folder (older versions), click on_config.yml
in the main list of files. - Click the pencil icon on the right to begin editing the file.
- Look for the
frontpage_goals_grid
section. - On the next line, change
title: Our data for Sustainable Development Goal indicators
to whatever you would like. For example, you might change the line to read:title: U.S. data for SDG indicators
. - Similarly, on the following line, change the
description
as well, to your own preferences. - Towards the bottom, select "Create a new branch for this commit and start a pull request."
- Beneath this, click "Propose changes".
- Click on the green "Create pull request" button.
- Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
- Wait until you see "All checks have passed". This takes about 5 minutes.
- Click on the green "Merge pull request" button.
View the results¶
Your site will now begin rebuilding. After about 5 minutes, if you visit your site, you should see the updated text on the frontpage.
Translate the new text¶
If you switch to a different language using the language-switcher, you will quickly notice a problem: the same text (whatever you chose to enter above) appears on all the languages. You need to translate this text so that it appears in the appropriate language.
The translations will be put in the data repository. You will be creating one file per language, starting with English. Here are the steps:
- Log in to Github.com, and go to your data repository.
- In the list of files, navigate to the
translations
folder. - Press the "Add file" drop-down and select "Create new file".
- In "Name your file" type
en/
and then typemy-custom-translations.yml
. (This name - my-custom-translations.yml - is arbitrary, but you will be referring to it later.) - Under "Edit new file", type
my-goals-grid-title:
followed by the text you entered above (in the "frontpage_goals_grid" section for "title"). - On the next line, type
my-goals-grid-description:
followed by the text you entered above (in the "frontpage_goals_grid" section for "description"). - Confirm that you have something that looks roughly like this:
my-goals-grid-title: Some text... my-goals-grid-description: Some other text...
- At the bottom select
Create a new branch for this commit and start a pull request.
- Click "Propose new file".
- Click on the green "Create pull request" button.
- Wait until you see "All checks have passed". This takes about 5 minutes.
- Click on the green "Merge pull request" button.
Next you will repeat these steps, but for Spanish:
- Still logged in to Github.com, go to your data repository.
- In the list of files, navigate to the
translations
folder. - Press the "Add file" drop-down and select "Create new file".
- In "Name your file" type
es/
and then typemy-custom-translations.yml
. (This name - my-custom-translations.yml - is arbitrary, but you will be referring to it later.) - Under "Edit new file", type
my-goals-grid-title:
followed by a Spanish translation of the text you entered above (in the "frontpage_goals_grid" section for "title"). - On the next line, type
my-goals-grid-description:
followed by a Spanish translation of the text you entered above (in the "frontpage_goals_grid" section for "description"). - Confirm that you have something that looks roughly like this:
my-goals-grid-title: AlgĂșn texto... my-goals-grid-description: AlgĂșn otro texto...
- At the bottom select
Create a new branch for this commit and start a pull request.
- Click "Propose new file".
- Click on the green "Create pull request" button.
- Wait until you see "All checks have passed". This takes about 5 minutes.
- Click on the green "Merge pull request" button.
If you have added any other language besides English and Spanish, repeat the steps as needed.
Update the frontpage configuration to use your translations¶
Now you need to go back to the site repository and tell it to use these new translations. The steps are as follows:
- Log in to Github.com, and go to your site repository.
- In the list of files, click into the
_data
folder and click onsite_config.yml
. Alternatively, you can alter this setting using the site configuration form. If you do not have the_data
folder (older versions), click on_config.yml
in the main list of files. - Click the pencil icon on the right to begin editing the file.
- As before, look for the
frontpage_goals_grid
section. - Change the two lines below it to the following:
title: my-custom-translations.my-goals-grid-title description: my-custom-translations.my-goals-grid-description
- Towards the bottom, select "Create a new branch for this commit and start a pull request."
- Beneath this, click "Propose changes".
- Click on the green "Create pull request" button.
- Wait a moment to see the message that says "Test PRs / test (pull_request) - in progress"
- Wait until you see "All checks have passed". This takes about 5 minutes.
- Click on the green "Merge pull request" button.
Before continuing, here is some detail on what you just did. You removed the text from these configuration settings, and you entered "translation keys".
Translation keys consist of 2 parts, separated by a dot (.
). The first part refers to the file containing the translations (in this case, my-custom-translations
) and the second part refers to the key within that file (in this case, my-goals-grid-title
and my-goals-grid-description
).
View your results¶
Your site will now begin rebuilding. After about 5 minutes, if you visit your site, you should be able to use the language-switcher and confirm that your custom frontpage text is now being translated correctly.
Troubleshooting¶
If this did not appear to work, please consult the troubleshooting page.