Installing on macOS¶
Hardware requirements¶
Weblate should run on any contemporary hardware without problems, the following is the minimal configuration required to run Weblate on a single host (Weblate, database and web server):
3 GB of RAM
2 CPU cores
1 GB of storage space
Note
Actual requirements for your installation of Weblate vary heavily based on the size of the translations managed in it.
Memory usage¶
The more memory the better - it is used for caching on all levels (file system, database and Weblate). For hundreds of translation components, at least 4 GB of RAM is recommended.
Hint
For systems with less memory than recommended, Single-process Celery setup is recommended.
CPU usage¶
Many concurrent users increase the amount of needed CPU cores.
Storage usage¶
The typical database storage usage is around 300 MB per 1 million hosted words.
Storage space needed for cloned repositories varies, but Weblate tries to keep their size minimal by doing shallow clones.
Nodes¶
For small and medium-sized sites (millions of hosted words), all Weblate components (see Architecture overview) can be run on a single node.
When you grow to hundreds of millions of hosted words, it is recommended to have a dedicated node for database (see Database setup for Weblate).
Installation¶
System requirements¶
Install the dependencies needed to build the Python modules (see Software requirements):
brew install python pango cairo gobject-introspection glib libyaml pkg-config zstd lz4 xxhash libxmlsec1 uv
Optionally install software for running production server, see Running server, Database setup for Weblate, Background tasks using Celery. Depending on size of your installation you might want to run these components on dedicated servers.
The local installation instructions:
# Web server option 1: NGINX and uWSGI
brew install nginx uwsgi
# Web server option 2: Apache with ``mod_wsgi``
brew install httpd
# Caching backend: Redis
brew install redis
# Database server: PostgreSQL
brew install postgresql
# Gettext for the msgmerge add-on
brew install gettext
Python modules¶
Hint
We’re using virtualenv to install Weblate in a separate environment from your system. If you are not familiar with it, check virtualenv User Guide.
Create the virtualenv for Weblate:
uv venv ~/weblate-env
Activate the virtualenv for Weblate:
. ~/weblate-env/bin/activate
Install Weblate including all optional dependencies:
# Install Weblate with all optional dependencies uv pip install "weblate[all]"
Please check Python dependencies for fine-tuning of optional dependencies.
Note
On some Linux distributions running Weblate fails with libffi error:
ffi_prep_closure(): bad user_data (it seems that the version of the libffi library seen at runtime is different from the 'ffi.h' file seen at compile-time)
This is caused by incompatibility of binary packages distributed via PyPI with the distribution. To address this, you need to rebuild the package on your system:
uv pip install --force-reinstall --no-binary :all: cffi
Configuring Weblate¶
Note
The following assumes the virtualenv used by Weblate is activated
(by executing . ~/weblate-env/bin/activate
). If not, specify the full path
to the weblate command as ~/weblate-env/bin/weblate
.
Copy the file
~/weblate-env/lib/python3.9/site-packages/weblate/settings_example.py
to~/weblate-env/lib/python3.9/site-packages/weblate/settings.py
.Adjust the values in the new
settings.py
file to your liking. You will need to provide at least the database credentials and Django secret key, but you will want more changes for production setup, see Adjusting configuration.Create the database and its structure for Weblate (the example settings use PostgreSQL, check Database setup for Weblate for a production-ready setup):
weblate migrate
See also
Create an administrator user account
admin
, generate its password, and copy it to the clipboard; remember to save it for later use:weblate createadmin
Hint
If you previously missed/lost the admin password, you can generate a new one with the following command:
weblate createadmin --update
See also
Collect the static files for your web server (see Running server and Serving static files):
weblate collectstatic
Compress the JavaScript and CSS files (optional, see Compressing client assets):
weblate compress
Start the Celery workers. This is not necessary for development purposes, but strongly recommended otherwise. Background tasks using Celery has more info:
~/weblate-env/lib/python3.9/site-packages/weblate/examples/celery start
Start the development server (Running server details a production setup):
weblate runserver
After installation¶
Congratulations, your Weblate server is now running and you can start using it.
You can now access Weblate on
http://localhost:8000/
.Sign in with admin credentials obtained during installation or register with new users.
You can now run Weblate commands using weblate command when Weblate virtualenv is active, see Management commands.
You can stop the test server with Ctrl+C.
Review potential issues with your installation either on
/manage/performance/
URL (see Performance report) or using weblate check --deploy, see Production setup.
Adding translation¶
Open the admin interface (
http://localhost:8000/create/project/
) and create the project you want to translate. See Project configuration for more details.All you need to specify here is the project name and its website.
Create a component which is the real object for translation - it points to the VCS repository, and selects which files to translate. See Component configuration for more details.
The important fields here are: Component name, Source code repository, and File mask for finding translatable files. Weblate supports a wide range of formats including GNU gettext PO (Portable Object), Android string resources, Apple iOS strings, Java properties, Stringsdict format or Fluent format, see Supported file formats for more details.
Once the above is completed (it can be lengthy process depending on the size of your VCS repository, and number of messages to translate), you can start translating.