You'll be writing a function called transliterate, which converts text from one writing system to another (a process called transliteration) You'll work with the Chitimacha writing system as an example (the language I work on in Louisiana).
The Chitimacha language has several writing systems: one that Morris Swadesh used to document the language back in the 1930s; the standard Americanist writing system that most linguists studying Native American languages use; and the modern tribal orthography. Below is a table comparing the three writing systems, and their IPA values:
IPA
APA
Swadesh
Modern
a
a
a
a
aː
aː
a·
aa
pˀ
pʼ
b
b
t͡ʃ
č
č
c
tˀ
tʼ
d
d
t͡sˀ
cʼ
ʒ
dz
e
e
e
e
eː
eː
e·
ee
kˀ
kʼ
g
g
h
h
h
h
i
i
i
i
iː
iː
i·
ii
t͡ʃˀ
čʼ
ǯ
j
k
k
k
k
m
m
m
m
n
n
n
n
o
o
o
o
oː
oː
o·
oo
p
p
p
p
ʔ
ʔ
ʔ
q
s
s
s
s
t
t
t
t
t͡s
c
c
ts
u
u
u
u
uː
uː
u·
uu
v
v
v
v
w
w
w
w
ʃ
š
š
x
j
y
y
y
Tasks
Here are your instructions. Remember you can (and should) commit your changes as you go, and sync them with GitHub. Then if you have any questions, I can go see where you're stuck.
Setup
[x] Clone the dlx-js repository onto your computer using GitHub desktop.
[x] Run npm install in the command line to install the necessary dependencies that dlx-js is using.
[x] Create a new branch off of the master branch called transliterate.
[x] Open the project in Atom and get familiar with what's in there:
The git folder with the GitHub database. Definitely don't want to change anything in this folder!
The docs folder is for developers, and includes documentation on how to use the dlx-js package. You can view the result online here.
The node_modules folder is all the other packages I've installed for this project. You never want to change anything in this folder.
The src folder holds the main code for the project. You should make all your changes here, in the dlx.js file.
The test folder holds all the tests that we run to make sure we don't break our code whenever we change something. As you write your transliterate function, I'll be writing tests to make sure it works like we expect it to, and you'll run those tests.
All the files that start with a period (.babelrc, .eslintrc, etc.) are settings/configuration files for the tools in this project. For example, the software Babel converts our code, which uses the latest fancy JavaScript syntax, to an older version of JavaScript so that even really old browsers can use it. The .babelrc file includes the settings for that.
dlx.js is the file converted by Babel. This is the file that people will use when they use our program in a browser. This file is automatically generated based on the src/dlx.js file. Don't make any changes to this file, only src/dlx.js. Any changes you make to this file will be overwritten each time the file is regenerated.
LICENSE - tells people that they can use our software as long as they give us credit for it.
package.json - General settings for the project. This has information that allows other people to install dlx-js using npm.
README.md - Instructions for people using our software.
[x] Practice running the build script.
In order to make our code ready for other people to install it, we have to do 2 tasks before we publish it: 1) Update the documentation; 2) Regenerate the dlx.js file for browsers to use. This is what's called our build process.
Rather than do this by hand, I've added a single script that takes care of both tasks at once. Whenever you're done making changes, run npm run build in the command line. Try running it now to make sure it works. (Nothing should change - it'll just regenerate dlx.js and the docs folder.
[x] Practice running the tests.
Every time you finish making a change, you should run the tests to make sure that everything is working as expected. If the tests break, you'll need to figure out what broke and fix it before you can merge your changes into the master branch (because we can't have broken code on the master branch).
There are two ways to run the tests. The easiest is to run npm test in the command line. Try it now to see if they pass. The other is to open the file test/index.html in the browser. You have to make sure you've regenerated the dlx.js file before running tests in the browser though. Try running the tests in the browser now by running npm run build in the command line, and then opening test/index.html in the browser. You should see a list of all the tests passing.
Code
[x] First, we're going to add a test that checks to make sure that your transliterate function exists. I've added this test to the transliterate-test branch. Using GitHub desktop, update your transliterate branch from the transliterate-test branch.
[x] Run the tests. You should see 1 test failing now, saying that the transliterate function doesn't exist. Your job now (the next couple steps) is to write the code that makes this test pass.
[x] Add an empty transliterate function to dlx.js, in alphabetical order with the other functions.
[x] Add your transliterate function as a property of the dlx object towards the bottom of the script. This makes it accessible to users when the dlx object is exported.
[x] Run the tests again to see if your code passes now.
[x] If everything passes, your code is ready to be merged! First, run the build script to update dlx.js and the docs folder.
[x] Commit and sync your changes, then open a pull request to the master branch.
[x] Delete the transliterate-test branch. We don't need it anymore since you copied that code over to your branch.
Overview
You'll be writing a function called
transliterate, which converts text from one writing system to another (a process called transliteration) You'll work with the Chitimacha writing system as an example (the language I work on in Louisiana).The Chitimacha language has several writing systems: one that Morris Swadesh used to document the language back in the 1930s; the standard Americanist writing system that most linguists studying Native American languages use; and the modern tribal orthography. Below is a table comparing the three writing systems, and their IPA values:
Tasks
Here are your instructions. Remember you can (and should) commit your changes as you go, and sync them with GitHub. Then if you have any questions, I can go see where you're stuck.
Setup
[x] Clone the
dlx-jsrepository onto your computer using GitHub desktop.[x] Run
npm installin the command line to install the necessary dependencies thatdlx-jsis using.[x] Create a new branch off of the
masterbranch calledtransliterate.[x] Open the project in Atom and get familiar with what's in there:
The
gitfolder with the GitHub database. Definitely don't want to change anything in this folder!The
docsfolder is for developers, and includes documentation on how to use thedlx-jspackage. You can view the result online here.The
node_modulesfolder is all the other packages I've installed for this project. You never want to change anything in this folder.The
srcfolder holds the main code for the project. You should make all your changes here, in thedlx.jsfile.The
testfolder holds all the tests that we run to make sure we don't break our code whenever we change something. As you write your transliterate function, I'll be writing tests to make sure it works like we expect it to, and you'll run those tests.All the files that start with a period (
.babelrc,.eslintrc, etc.) are settings/configuration files for the tools in this project. For example, the software Babel converts our code, which uses the latest fancy JavaScript syntax, to an older version of JavaScript so that even really old browsers can use it. The.babelrcfile includes the settings for that.dlx.jsis the file converted by Babel. This is the file that people will use when they use our program in a browser. This file is automatically generated based on thesrc/dlx.jsfile. Don't make any changes to this file, onlysrc/dlx.js. Any changes you make to this file will be overwritten each time the file is regenerated.LICENSE- tells people that they can use our software as long as they give us credit for it.package.json- General settings for the project. This has information that allows other people to installdlx-jsusing npm.README.md- Instructions for people using our software.[x] Practice running the build script.
dlx.jsfile for browsers to use. This is what's called our build process.npm run buildin the command line. Try running it now to make sure it works. (Nothing should change - it'll just regeneratedlx.jsand thedocsfolder.[x] Practice running the tests.
masterbranch (because we can't have broken code on themasterbranch).npm testin the command line. Try it now to see if they pass. The other is to open the filetest/index.htmlin the browser. You have to make sure you've regenerated thedlx.jsfile before running tests in the browser though. Try running the tests in the browser now by runningnpm run buildin the command line, and then openingtest/index.htmlin the browser. You should see a list of all the tests passing.Code
transliteratefunction exists. I've added this test to thetransliterate-testbranch. Using GitHub desktop, update yourtransliteratebranch from thetransliterate-testbranch.transliteratefunction doesn't exist. Your job now (the next couple steps) is to write the code that makes this test pass.transliteratefunction todlx.js, in alphabetical order with the other functions.transliteratefunction as a property of thedlxobject towards the bottom of the script. This makes it accessible to users when thedlxobject is exported.dlx.jsand thedocsfolder.masterbranch.transliterate-testbranch. We don't need it anymore since you copied that code over to your branch.