Weblate

Overview

Weblate is a self-hostable localization tool. It’s most commonly used for crowd-sourcing the translation of strings.

Features

Checks exist to catch mistakes. E.g. if I have a C# string in English like “Your total is {0}”, then it will make sure that the Spanish string also includes “{0}” and not higher numbers like “{1}”, since both would imply mistakes.

Setup

I installed it through Docker following these steps.
I don’t trust that Weblate is bulletproof, so I set Weblate up with its own GitHub repo and email address.
- The GitHub repo should only have translation files. Your main application’s repo should use the translation repo as a submodule.
- The email address just needs to be anything that lets you use SMTP. Gmail will suffice.
  - You need an app password to send emails through Gmail, which requires that 2-step verification is on.
If you need to make changes to your docker-compose.override.yml while setting up, just ctrl+C the currently running docker compose up and start it again. The YAML I used for setting everything up:

services:
  weblate:
    image: weblate/weblate:latest
    environment:
      # Only allow registration on the whole Weblate instance through invitation
      WEBLATE_REGISTRATION_OPEN: 0

      # No real need for captchas if I'm only adding people via invitation
      WEBLATE_REGISTRATION_CAPTCHA: 0

      WEBLATE_EMAIL_HOST: smtp.gmail.com
      WEBLATE_EMAIL_PORT: 465
      WEBLATE_EMAIL_USE_TLS: 0
      WEBLATE_EMAIL_USE_SSL: 1
      WEBLATE_EMAIL_HOST_USER: this_is_your_gmail_name
      WEBLATE_EMAIL_HOST_PASSWORD: 'your-app-password-with-no-spaces'

      # Your users will see emails from this address when they sign up
      WEBLATE_DEFAULT_FROM_EMAIL: you@example.com
      WEBLATE_SERVER_EMAIL: you@example.com
      WEBLATE_SITE_DOMAIN: weblate.example.com

      # You will sign in to Weblate using this email (or "admin" as your username)
      WEBLATE_ADMIN_EMAIL: you@example.com

      # This is specifically for use with reverse proxies (like Cloudflare tunnels)
      # where THEY provide HTTPS even though we only ever expose Weblate over HTTP.
      WEBLATE_SECURE_PROXY_SSL_HEADER: HTTP_X_FORWARDED_PROTO,https

      # Prevent logging 127.0.0.1 when behind a Cloudflare tunnel. If you're using
      # a different reverse proxy, then you can drop the WEBLATE_IP_PROXY_HEADER
      # bit since it defaults to HTTP_X_FORWARDED_FOR.
      #
      # Note: this is NOT just cosmetic; the IP address is used for rate-limiting.
      WEBLATE_IP_PROXY_HEADER: HTTP_CF_CONNECTING_IP
      WEBLATE_IP_BEHIND_REVERSE_PROXY: 1

      # I suggest deleting this immediately after setting Weblate up since this
      # will otherwise keep overwriting your password. This is purposely
      # insecure to get you to change the password when you sign in (then delete
      # this line).
      WEBLATE_ADMIN_PASSWORD: hunter2

    ports:
    # I'm running on a machine with other services, and this'll be exposed
    # through Cloudflare tunnel, hence why I don't want to use port 80.
    - 3010:8080

Note: EMAIL_* (as opposed to WEBLATE_EMAIL_*) is the underlying Django configuration and shouldn’t be needed; you set it through WEBLATE_EMAIL_* variables.

Add a project on Weblate
When it comes to adding the GitHub repo (which happens when making a component on Weblate):
- Go to the /manage/ssh/ URL in Weblate.
- Add “github.com” into “Add host key” at the bottom and press enter.
- They recommend making a special user on GitHub purely for your Weblate stuff, so I made one with the Gmail account from above.
  - Then, add the SSH key from /manage/ssh in Weblate to your new GitHub account.
  - Add the new GitHub account as a collaborator on your translations repo.
  - Finally, make sure your repo URL in Weblate is the SSH address, not the HTTPS address, e.g. git@github.com:YourGitHubName/your-repo-name.git
Expose the service through a Cloudflare tunnel (see Cloudflare#Tunnel).

Other setup notes:

Make sure to go through Insights → Community Localization Checklist for your component. It’ll have you set up a GitHub webhook, which is pretty easy.
- Note: the URL for the localization checklist is /guide/YOUR_PROJECT_NAME/YOUR_COMPONENT_NAME/.

Administration

Basics
- Add new users via 🔧 → Users → scroll to “Add new user”. Add them to the “Users” team, which is a site-wide team.
  - You still need to add them to a project team after that, e.g. “Skeleseller” → “Translate”. However, I think you can automate this (maybe) via Settings → Teams → Users → click the “Translate” role under “Users” → Save.
- Commit/push your repo via your project’s page → Operations → Repository Maintenance.
If installed with Docker, you can run some commands directly in the container:
- docker exec -it DOCKER_CONTAINER_ID bash
- Once inside, run weblate to see all possible commands. E.g. weblate shell will give a Django shell that you could use to, say, directly create a user (see how the official code calls create_user here):
  - weblate shell -c "from django.contrib.auth import get_user_model; User = get_user_model(); u = User.objects.create_user(username='toto', email='toto@example.com', full_name='Toto'); u.set_password('toto'); u.is_active = True; u.save()"
- E.g. you can change a password via weblate changepassword --help