|
|
[[_TOC_]]
|
|
|
|
|
|
All the lektor-based websites work the same, although they have different repositories. This howto was written for the Tor Project main website repository address, https://gitlab.torproject.org/tpo/web/tpo.git, but it can also work for:
|
|
|
|
|
|
* [Tor Browser Manual](https://tb-manual.torproject.org/): `https://gitlab.torproject.org/tpo/web/manual.git`
|
|
|
* [Support Portal](https://support.torproject.org/): `https://gitlab.torproject.org/tpo/web/support.git`
|
|
|
* [Community portal](https://community.torproject.org/): `https://gitlab.torproject.org/tpo/web/community.git`
|
|
|
* [GetTor webpage](https://gettor.torproject.org/): `https://gitlab.torproject.org/tpo/anti-censorship/gettor-project/gettor-web.git`
|
|
|
* [Donation page](https://donate.torproject.org/): `https://gitlab.torproject.org/tpo/web/donate-static.git`
|
|
|
|
|
|
### **1. Install Python 3.8**
|
|
|
|
|
|
Download and install [Python 3.8][]. If you're on linux, your package manager might provide a `python3.8` package.
|
|
|
|
|
|
*Why Python 3.8?*
|
|
|
|
|
|
Our websites use [lektor-i18n-plugin][] for internationalization. The plugin requires Python 3.8 to workaround a [a bug in the plugin][]. Using a newer version of Python will cause issues compiling the site. This isn't ideal, but it's our best solution for now.
|
|
|
|
|
|
[Python 3.8]: <https://www.python.org/downloads/release/python-3810/>
|
|
|
[lektor-i18n-plugin]: <https://github.com/numericube/lektor-i18n-plugin>
|
|
|
[a bug in the plugin]: <https://gitlab.torproject.org/tpo/web/lego/-/issues/37>
|
|
|
|
|
|
### **2. Clone the repo from gitlab.torproject.org**
|
|
|
|
|
|
Run the following shell command
|
|
|
|
|
|
```sh
|
|
|
git clone https://gitlab.torproject.org/tpo/web/tpo.git && cd tpo
|
|
|
```
|
|
|
|
|
|
### **3. Set up a virtual Python environment**
|
|
|
|
|
|
This step isn't strictly necessary, but without it Lektor will globally install plugins, causing build issues.
|
|
|
|
|
|
```sh
|
|
|
python3.8 -m venv venv
|
|
|
source venv/bin/activate
|
|
|
pip install --upgrade pip lektor
|
|
|
```
|
|
|
|
|
|
You can deactivate the virtual environment at any time by running `deactivate`.
|
|
|
|
|
|
### **4. Install the [dependencies for the lektor-i18n-plugin](https://github.com/numericube/lektor-i18n-plugin#prerequisites)**
|
|
|
|
|
|
lektor-i18n-plugin requires gettext and python3-babel. On Debian these can be installed with
|
|
|
|
|
|
You can do this by running the following commands:
|
|
|
|
|
|
```sh
|
|
|
sudo apt-get install gettext python3-babel
|
|
|
```
|
|
|
|
|
|
### **5. Clone the translations repository**
|
|
|
|
|
|
Download the correct branch of the translations repo to the `./i18n/` folder:
|
|
|
|
|
|
```sh
|
|
|
git clone --single-branch --branch tpo-web https://gitlab.torproject.org/tpo/translation.git i18n
|
|
|
```
|
|
|
|
|
|
Make sure to change `--branch tpo-web` to the correct branch. For the other websites, the branches are: `tbmanual-contentspot`, `support-portal`, `communitytpo-contentspot`
|
|
|
|
|
|
### 6. Initialize the building blocks submodule
|
|
|
|
|
|
We use a common "building blocks" submodule to make sure our sites look the same. We call this submodule lego. Run this command to initialize it:
|
|
|
|
|
|
```sh
|
|
|
git submodule update --init --recursive --remote
|
|
|
```
|
|
|
|
|
|
This will clone lego into the `./lego/` directory. Your local copy of the site will already have symlinks set up to point to lego files where needed.
|
|
|
|
|
|
### 7. Install and use Lektor i18n plugin
|
|
|
|
|
|
The plugins are installed when you start the lektor server locally or you build the website.
|
|
|
|
|
|
The translation mechanism is hooked into the build system, so translating a website just means building the website. You can learn more about the translation process [here](https://gitlab.torproject.org/tpo/community/l10n/-/wikis/Home).
|
|
|
|
|
|
`lektor build -O <folder>` builds the website in a folder of your choice
|
|
|
|
|
|
`lektor s` runs a lektor server and allows you to have the website updating on `http://localhost:5000`. You can try this out by running the server and accessing it on your browser.
|
|
|
Note: It will not work on Tor Browser. :)
|
|
|
|
|
|
**NOTE:** Due to how the lektor-i18n-plugin works, you'll need to build the lektor site twice after cloning it to get the translation files in place. Once you've done that, You can just build a single time like normal to see your changes.
|
|
|
|
|
|
> **Tip**: To save some time while you build in local, you can edit the [configs/i18n.ini](https://gitweb.torproject.org/project/web/tpo.git/tree/configs/i18n.ini) file and take some languages out of the 'translations' option.
|
|
|
|
|
|
You can make changes to the pages. Most of [the content is on the `content/` folder](https://gitlab.torproject.org/torproject/web/tpo/wikis/Writing-the-content).
|
|
|
|
|
|
### 8. Finally, local server
|
|
|
enter `$ lektor server` to run a local continuous builder.
|
|
|
You should be able to access your local lektor instance at [http://127.0.0.1:5000/](http://127.0.0.1:5000/) from your computer.
|
|
|
|
|
|
# Most common lektor errors
|
|
|
|
|
|
##### FileNotFoundError:
|
|
|
FileNotFoundError: [Errno 2] No such file or directory: '/content/**some filename**/contents.lr'
|
|
|
|
|
|
This happens when a source file `contents.lr` has been deleted in the repository, but their associated language files are still there. So, when trying to update the language files, lektor fails because the source file is not there. Delete the folder with the translations and build again:
|
|
|
|
|
|
rm -r '/content/**some filename**/'
|
|
|
|
|
|
##### Update lego
|
|
|
|
|
|
Example:
|
|
|
/training/code-of-conduct/index.html (jinja2.exceptions.UndefinedError: 'render_text' is undefined)
|
|
|
|
|
|
Can be fixed with `git submodule update --init --recursive`
|
|
|
|
|
|
##### SyntaxError
|
|
|
except IOError, e: SyntaxError: invalid syntax
|
|
|
|
|
|
This can be the python version. Try it with Python 2.7 to 3.7
|
|
|
|
|
|
* If you encounter the error: `from urllib import requestImportError: cannot import name request`, you can fix it by going to `~tpo/lego/packages/xml-to-html/lektor_xml_to_html.py` and changing the line `from urllib import request` to `from urllib3 import request`. You may also have to do the same change for the `~tpo/lego/packages/txt-to-html/lektor_txt_to_html.py` file.
|
|
|
|
|
|
* A possible error is `UnicodeEncodeError: 'ascii' codec can't encode character u'\xae'` stemming from `~tpo/lego/packages/i18n/lektor_i18n.py`. This can be fixed by adding the following code snippet to the top of the page after the `import sys` phrase:
|
|
|
```
|
|
|
reload(sys)
|
|
|
sys.setdefaultencoding('utf8')
|
|
|
```
|
|
|
|
|
|
##### 'i18n' already exists
|
|
|
|
|
|
If `git clone https://gitlab.torproject.org/tpo/translation.git i18n` fails with:
|
|
|
|
|
|
fatal: destination path 'i18n' already exists and is not an empty directory.
|
|
|
|
|
|
This happens if you tried to build lektor before downloading the translations. You need to remove that directory and try cloning again:
|
|
|
|
|
|
rm -r 'i18n'
|
|
|
git clone https://gitlab.torproject.org/tpo/translation.git i18n
|
|
|
|
|
|
##### babel.cfg not found
|
|
|
|
|
|
If when building the website you get the error:
|
|
|
|
|
|
"FileNotFoundError: [Errno 2] No such file or directory: 'babel.cfg'"
|
|
|
|
|
|
You are not on the root directory for lektor. Go to the root directory and try again.
|
|
|
|
|
|
##### Weird characters between lines on the website
|
|
|
Sometimes the paragraphs of the website will be mixed with phrases like: `Project-Id-Version: PACKAGE VERSION Report-Msgid-Bugs-To: PO-Revision-Date: 2018-11-14 12:31+0000 Last-Translator: ...`
|
|
|
|
|
|
![scruff-on-lektor-local](uploads/0715ecc33a5bf18964127733a812ba6c/scruff-on-lektor-local.png)
|
|
|
|
|
|
This means that the i18n plugin has not been able to update the pages well.
|
|
|
You need to run `lektor build` more times for this text to disappear.
|
|
|
|
|
|
If the unwanted text is still present after building the site multiple times, you might be using Python 3.9 or higher. The lektor-i18n-plugin requires Python 3.8 to work.
|
|
|
|
|
|
##### Setuptools error
|
|
|
|
|
|
If when building the website you get the error:
|
|
|
|
|
|
```
|
|
|
Collecting setuptools>=38.2.5
|
|
|
Using cached https://files.pythonhosted.org/packages/a8/e7/1440b0d19054a5616e9e5beeaa22f68485aa9de20d187f04e52880b7ae7a/setuptools-59.2.0.tar.gz
|
|
|
Installing build dependencies: started
|
|
|
Installing build dependencies: finished with status 'error'
|
|
|
Complete output from command /usr/bin/python3 -m pip install --ignore-installed --no-user --prefix /tmp/pip-build-env-4e9g0x0f --no-warn-script-location --no-binary :all: --only-binary :none: -i https://pypi.org/simple --:
|
|
|
ERROR: You must give at least one requirement to install (see "pip help install")
|
|
|
|
|
|
----------------------------------------
|
|
|
Command "/usr/bin/python3 -m pip install --ignore-installed --no-user --prefix /tmp/pip-build-env-4e9g0x0f --no-warn-script-location --no-binary :all: --only-binary :none: -i https://pypi.org/simple --" failed with error code 1 in None
|
|
|
|
|
|
----------------------------------------
|
|
|
Command "/usr/bin/python3 -m pip install --ignore-installed --no-user --prefix /tmp/pip-build-env-xojjpvj9 --no-warn-script-location --no-binary :all: --only-binary :none: -i https://pypi.org/simple -- setuptools>=38.2.5 wheel" failed with error code 1 in None
|
|
|
```
|
|
|
|
|
|
You will need to upgrade your `pip` and run `lektor server` again:
|
|
|
|
|
|
pip3 install --upgrade pip
|
|
|
|
|
|
##### Changes to content or templates not showing up after building
|
|
|
|
|
|
If you build a site, make changes, and build the site again, Lektor might not rebuild the file. If you're wondering why your changes aren't showing up, try running `lektor clean --yes` and re-building. This forces lektor to build from scratch. It can take a while, but it might fix your problem. THe translation files will already be in place, so you won't need to build from scratch multiple times.
|
|
|
|
|
|
### DONE
|
|
|
|
|
|
Great! You are set! Now you can start [developing on the website](./How-to-develop-on-the-website), or also [write content](./Writing-the-content)
|
|
|
|
|
|
------------------------
|
|
|
|
|
|
To update this wiki, please do a PR to https://gitlab.torproject.org/torproject/web/wiki |