Skip to content

Latest commit

 

History

History
146 lines (102 loc) · 4.93 KB

CONTRIBUTING.md

File metadata and controls

146 lines (102 loc) · 4.93 KB
Raw

Contributors' Guide

Translating to your own language is perhaps the most useful thing you can do for the project currently, as Amazon rolls out more and more language support for Alexa.

Developing

Where to start

Generally, have a look at tickets marked help wanted or good first issue.

Generally pull requests are accepted if they:

  • Address a Github issue where the approach has been discussed
  • Pass all automated tests and linting
  • Don't reduce the test coverage
  • Are clearly written, and in a Pythonic way
  • Use the current (ever changing...) best practices for Alexa skills
  • 🆕 use Python 3.5+ features where appropriate (in particular typing) 3.6 features can't currently be used for mqtt-squeeze.

Building

The project is now Python 3.6+ only, and we use Tox Pipenv Poetry (see #114).

Testing

We use PyTest and plugins for testing. You can run tests with

poetry run pytest

Testing is very important in this project, and coverage is high. Please respect this!

Coverage is reported in Coveralls.

Code Quality

poetry run flake8 --statistics .

No output / error code means everything is good...

Releasing

This is mostly automated now:

bin/build.sh
bin/release.sh 3.0

will create releases/squeeze-alexa-3.0.zip (hopefully) suitable for upload to Github etc.

Translation

squeeze-alexa uses GNU gettext for its output. It's a little old-fashioned / troublesome at first, but it serves its purposes well.

I have a new language

Great! Follow these steps (imagine you are choosing Brazilian Portuguese, pt_BR):

Create a directory

cd locale
LOCALE=pt_BR
mkdir -p $LOCALE/LC_MESSAGES

Generate a blank PO file

DOMAIN=squeeze-alexa
touch $LOCALE/LC_MESSAGES/$DOMAIN.po

Update translations from source

This re-scans the source and recreates a master .pot file, before then updating the translations files (.pos).

bin/update-translations

Translate your .po

You can edit the using any text editor, or use PoEdit, or any other gettext tools e.g.

Compile translations

This takes the .pos and makes binary .mos that are necessary for gettext to work.

bin/compile-translations

Add utterances and slots

Amazon changed the way they handle interaction. The original way (v0) used separate input for slots and utterances. In interaction model v1, among other changes, they've merged this into one big JSON which is probably easier in the long run.

squeeze-alexa (documentation) now "supports" both

v0 schema

  • Refer to the v0 intents.json.
  • Add an utterances.txt in the right locale directory e.g. metadata/intents/v0/locale/pt_BR/utterances.txt (see German example)
  • Optional: do the same for the SLOT (genres, playlist names, player names etc)

...or v1 schema

  • Create a new locale directory, e.g. pt_BR under metadata/v1/locale.
  • Translate the whole English file v1 intents.json to a copy of the same name under that new directory.

Submit the translations

  • Hopefully you opened a Github issue - if not, do this.
  • Either
    • attach the updated .po and utterances / intents files, or
    • create a fork in Github, branch, commit your new file(s) in Git, then make a Pull Request, mentioning the ticket number.

Translation FAQ

Everything's still in US English

  • Make sure you've set LOCALE in settings.py.
  • Make sure the directory is setup as above and you've definitely compiled it (i.e. there's a .mo file)
  • New versions of squeeze-alexa default to the source language (en_US) if there is no translation found.

What if I don't translate some strings?

No problem. They'll come out in the source language (en here).

I'm getting "invalid multibyte sequence" errors

This .po header is probably missing:

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"

There are newlines I didn't expect

xgettext reformats source files to a maximum line width according to its settings. See update-translations for the setup.