Skip to content

Translation

Jump to bottom
eikek edited this page Apr 10, 2024 · 6 revisions

Translation

Help with translating is much appreciated. This document should show how the webui can be translated.

How to translate

It requires to code a little in Elm. But it's not that much….

This guide is meant to non-programmers who are open to modifying source code anyways.

Preparation

You need to install git, sbt and Elm in order to compile the sources. This is necessary to see the translated ui.

If you have nix installed, run nix develop in the source root, which drops into an environment with all required tools available.

Clone the repository using git. Open a terminal and run:

git clone https://github.com/eikek/sharry.git

Go into the new directory and run sbt. After sbt has finished starting up you are in the "sbt shell". Start the webapp by typing first make and then reStart (case sensitive).

/tmp> cd sharry
/t/sharry (master)> sbt
[info] Loading settings for project global-plugins from plugins.sbt,metals.sbt ...
[info] Loading global plugins from /home/eike/.dotfiles/sbt/.sbt/1.0/plugins
[info] Loading settings for project sharry-build from plugins.sbt ...
[info] Loading project definition from /tmp/sharry/project
[info] Updating
[info] Resolved  dependencies
[info] Fetching artifacts of
[info] Fetched artifacts of
[warn] There may be incompatibilities among your library dependencies; run 'evicted' to see detailed eviction warnings.
[info] Compiling 2 Scala sources to /tmp/sharry/project/target/scala-2.12/sbt-1.0/classes ...
[info] Loading settings for project root from build.sbt,version.sbt ...
[info] Set current project to sharry-root (in build file:/tmp/sharry/)
[info] sbt server started at local:///home/eike/.sbt/1.0/server/c65a96364d30f89e49b4/sock
sbt:sharry-root> make

This compiles everything. This step is required once at start to generate missing files and compile source code

To start the development server, run

sbt:sharry-root> reStart

If the terminal gets a bit quiter from all the output run the last command: ~compile. The ~ tells sbt to recompile if a source file changes.

Alternatively to using the ~compile task, you can use the bash script project/dev-build-ui.sh. Run the reStart as described above and then open a new terminal and run this script:

./project/dev-ui-build.sh watch

This compiles the elm sources only if they have changed which is very fast and when doing translation in the ui this is enough. The ~compile task is a bit slower since it also compiles the css file.

Now you can point your browser to http://localhost:9090 and see the app. You can modify the Elm sources and see the changes after refreshing the browser.

Find the sources

The webapp is in the module modules/webapp and the Elm sources are in modules/webap/src/main/elm. All strings are in the Messages/*.elm source files. The Messages.elm file contains the entry point: it defines all available languages.

The following shows an example for adding a new language.

Example: Adding German

Adding the new language

Start by editing Messages.elm and add the new language as another branch to the type Language. Example for German:

type Language
    = English
    | German

It must start with a pipe character | followed by the language name. Choose the English version of the language as this is source code.

Also add it to the list of all languages below:

allLanguages : List Language
allLanguages =
    [ English
    , German
    ]

If you make a mistake, the Elm compiler informs you and also gives some advice. It is usually quite helpful.

The compiler should now tell you this:

Detected problems in 1 module.
-- MISSING PATTERNS ------------------- modules/webapp/src/main/elm/Messages.elm

This `case` does not have branches for all possibilities:

92|>    case lang of
93|>        English ->
94|>            gb

Missing possibilities include:

    German

I would have to crash if I saw one of those. Add branches for them!

Hint: If you want to write the code for each branch later, use `Debug.todo` as a
placeholder. Read <https://elm-lang.org/0.19.1/missing-patterns> for more
guidance on this workflow.

So around line 92 is something wrong. It is the place where a set of all strings is returned given some language. Currently there is only one set of strings for English that you'll find at the end of the file. So to start, just copy this set and rename it to de.

de : Messages
de =
    { lang = German
    , iso2 = "de"
    , label = "Deutsch"
    , flagIcon = "flag-icon flag-icon-de"
    , app = Messages.App.gb
    , login = Messages.LoginPage.gb
    , register = Messages.RegisterPage.gb
    , account = Messages.AccountPage.gb
    , aliasPage = Messages.AliasPage.gb
    , detail = Messages.DetailPage.gb
    , share = Messages.SharePage.gb
    , home = Messages.HomePage.gb
    , upload = Messages.UploadPage.gb
    , newInvite = Messages.NewInvitePage.gb
    , settings = Messages.SettingsPage.gb
    }

Change lang, iso2, label and flagIcon appropriately. The label should contain the native language name (not in English), as this is now the label that is shown to users. For the flag icon, just change the iso2 code or see the flag-icon-css page.

Then the error around line 92 can be fixed:

get : Language -> Messages
get lang =
    case lang of
        English ->
            gb

        German ->
            de

The code now compiles successfully. If you refresh the browser, you should be able to change to the new language (with no effect, since the strings are not translated yet).

Translating

Now the translation work can start. If you look at the new value de, you'll see a few set of strings. Each corresponds to a page: login is for the login page, home is for the "home page" etc; and app is for the top menu.

Take one of them and start translating. For the example, I use the first one which is Messages.App. The file to this is in Messages/App.elm. Open this file and you'll see a gb value. Copy this to de and start translating.

de : Texts
de =
    { home = "Home"
    , shares = "Shares"
    , aliases = "Aliase"
    , accounts = "Konten"
    , settings = "Einstellungen"
    , newInvites = "Einladungen"
    , logout = \user -> "Abmelden (" ++ user ++ ")"
    , login = "Anmelden"
    , register = "Registrieren"
    }

Then go to the beginning of the file and add the new de value to the list of “exposed” values. This is necessary so it can be used from withing the Messages.elm file.

module Messages.App exposing
    ( Texts
    , de {- the new value -}
    , gb
    )

Now go back to Messages.elm and exchange Messages.App.gb with Messages.App.de.

de : Messages
de =
    { lang = German
    , iso2 = "de"
    , label = "Deutsch"
    , flagIcon = "flag-icon flag-icon-de"
    , app = Messages.App.de
    , login = Messages.LoginPage.gb
    , register = Messages.RegisterPage.gb
    , account = Messages.AccountPage.gb
    , aliasPage = Messages.AliasPage.gb
    , detail = Messages.DetailPage.gb
    , share = Messages.SharePage.gb
    , home = Messages.HomePage.gb
    , upload = Messages.UploadPage.gb
    , newInvite = Messages.NewInvitePage.gb
    , settings = Messages.SettingsPage.gb
    }

Then go to the next and start over. It happens that some page files contain other string-sets of certain components. Then just follow this guide recursively.

You can check the translation in the browser.

Publishing

You can publish your work to this repo in various ways:

Github PR

The prefered one is using your github account creating a pull request. This is a quick walk-through. There is thorough help at github.

  1. Fork this repository in the github webapp.
  2. Go to the sharry source root you just checked out in a terminal. 
    git remote rename origin upstream
git remote add origin [email protected]:<your-github-name>/sharry.git
git fetch --all
  3. Create a new git branch: 
    git checkout -b translate origin/master
  4. Make a commit of your changes: 
    git config user.name "Your Name"
git config user.email "Your Email" #(note that this email will be publicly viewable! a dummy address is fine, too)
git commit -am 'Add translation for German'
    (Modify the message to your needs)
  5. Push the change to your repository 
    git push origin translate
  6. Go to the github ui and create a pull request.

E-Mail

You can send me the patch via e-mail. You can use git send-email or your favorite e-mail client. For this do step 4) from above and then

git bundle create translation.bundle origin/master..HEAD

Then send the created translate.bundle file. If this command doesn't work, try:

git format-patch origin/master..HEAD

This results in one or more 0001-… files that you can send.

Any other

Contact me by mail or create an issue.

Clone this wiki locally