Visualizing your data

These guides assume you are comfortable with the Command Line, Git and NPM. You must have all of these installed on your machine. You are also strongly encouraged to have a GitHub account. You are encouraged to fork or clone the Mother Tongues Dictionary Starter and follow along.

Adding a User Interface

This is a guide for visualizing your data through a user interface.

important

This guide assumes you have worked through all the steps in preparing your data.

Exporting your data

First, you need to export the JavaScript files required by any MTD UI.

  1. Change directories to your MTD folder.
  2. Then, build the dictionary using the mtd export command to create necessary JavaScript files. For example, given a dictionary named abc, a Language configuration file named abc_config.json, and a desired output folder output, run the following:

mtd export abc_config.json js output

Because we are in our MTD folder, we can just run mtd export . js .

note

This command will compile ALL the configuration files in the current directory.

You will see various messages displayed, potentially including info, warnings, and errors, which are ordered in terms of severity. If there are only info messages, the command executed successfully, and the info might advise you on how to improve your configuration inputs. If there are warnings (which may be in addition to info messages), the command executed but there might be serious issues with the output files. If there are errors (which may be in addition to info messages and warnings), the command did not execute successfully.

Checking your output folder, you should see two files: config-abc.js and dict_cached-abc.js. These files contain the data for your dictionary.

Once you have built your dictionary files, you can add them to a dictionary UI such as an MTD mobile UI or MTD web UI.

tip

By simply changing the config-*.js and dict_cached-*.js files in your MTD Starter (and updating the index.html if the filenames changed) GitHub will automatically build your dictionary using the MTD mobile UI. Note that you will have to enable GitHub Actions on your MTD starter for the automatic builds to work.

MTD Mobile

Here are the steps for creating a mobile dictionary on your machine.

  1. Fork the repository in GitHub:
fork mtd ui
  1. Clone your fork onto your local machine:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/mothertongues-ui.git

  1. Add the original repo as another remote so you can pull changes later:

git remote add mtd https://github.com/roedoejet/mothertongues-ui.git

  1. Change into the directory:

cd mothertongues-ui

  1. Install dependencies:

npm install

  1. Move your exported data to mothertongues-ui/src/assets/js and change the names to just config.js and dict_cached.js respectively, overwriting the config and data files that are already there.

  2. Run your dictionary:

ionic serve

MTD Web

Here are the steps for creating a web dictionary on your machine.

  1. Fork the repository in GitHub:
fork mtd web ui
  1. Clone your fork onto your local machine:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/mothertongues-ui-web.git

  1. Add the original repo as another remote so you can pull changes later:

git remote add mtd https://github.com/mothertongues/mothertongues-ui-web.git

  1. Change into the directory:

cd mothertongues-ui-web

  1. Install dependencies:

npm install

  1. Move your exported data to mothertongues-ui-web/projects/mtd/src/assets/js and change the names to just config.js and dict_cached.js respectively, overwriting the config and data files that are already there.

  2. Run your dictionary:

npm start

  1. Commit your changes and push. Your site will be published at https://<YOUR_GITHUB_HANDLE>.github.io/mothertongues-UI-Web/:

git commit -a -m 'updated data' && git push origin master

File structure

Below is an incomplete snapshot of the file structure for a MTD Web dictionary

📦mothertongues-UI-Web
┣ 📂projects
┃ ┣ 📂mtd
┃ ┃ ┗ 📂e2e
┃ ┃ ┗ 📂src
┃ ┃ ┗ 📂e2e
┃ ┃ ┗ 📂app
┃ ┃ ┗ 📂assets
┃ ┃ ┗ 📂config
┃ ┃ ┗ 📂environments
┃ ┃ ┗ 📂themes
┃ ┃ ┗ 📜styles.scss
┃ ┗ 📂server
┣ 📂src
┣ 📂www
┣ 📜angular.json
┣ 📜package.json

Configuring your dictionary

Your dictionary configuration file is found inside the 'config' folder in the MTD UI Web project.

The config.ts file contains an object called META which is where you should configure your app.

export const META: Meta = {
browseAudio: true,
contributors: [
{
name: 'Aidan Pine',
title: 'Lead Developer',
text:
/* tslint:disable */
"Here is where you description of the person goes. You can put plain text, or <b>even</b> mark it up with <i>html</i>",
img: false
}
],
languages: [{ label: 'en', value: 'en' }],
copyright: {
name: 'Mother Tongues',
url: 'https://mothertongues.org'
},
links: {
github: {
display: false,
url: ''
},
medium: {
display: false,
url: ''
},
facebook: {
display: false,
url: ''
},
youtube: {
display: false,
url: ''
}
}
};

Adding translations

You can translate the entire interface to your Mother Tongues dictionary by doing the following:

  1. Add the language to the languages array in the META config (currently only english is there). You should use a 2 or 3 character abbreviated form here. You will have the chance to give a full name to the language later.

  2. Add an empty file to mothertongues-UI-Web/projects/mtd/src/assets/i18n/ with your language's configured 2 or 3 character form.

tip

Example, dan.json for Danish.

  1. From the root of the project, run npm run-script extract-translations

  2. Translate all of the empty strings in your new translation file. Either do it directly in the json file, or upload it to a service like POEditor for collaborative translations.

Then, when you rebuild your app, the user will have the option to translate into your language 🎉