ringtools/docs
1
0
Fork 0
mirror of https://github.com/ringtools/docs.git synced 2024-11-19 04:20:01 +01:00
Code Issues Projects Releases Wiki Activity

Initial commit RTD

Browse Source
This commit is contained in:
Djuri Baars 2022-05-09 01:08:58 +02:00
commit 6b430b61de
30 changed files with 1370 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.gitignore vendored Normal file
View File

@ -0,0 +1,13 @@
*.pyc
*.egg-info
_build
_readthedocs_build
autoapi
_build_rtd
build
.idea/
.tox
.cache
.python-version
dist
tags

29
.readthedocs.yaml Normal file
View File

@ -0,0 +1,29 @@
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
python: "3.9"
# You can also specify other tool versions:
# nodejs: "16"
# rust: "1.55"
# golang: "1.17"
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: source/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
# formats:
# - pdf
# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: requirements.txt

201
LICENSE Normal file
View File

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

25
Makefile Normal file
View File

@ -0,0 +1,25 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
gettext:
@$(SPHINXBUILD) -b gettext "$(SOURCEDIR)" "$(BUILDDIR)/gettext"
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

656
README.md Normal file
View File

@ -0,0 +1,656 @@
# Transifex Client
## Installation
### Installing with a script (Linux/Mac)
You can install the Transifex CLI by executing:
```
curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
```
This script will:
* Try to find the correct version for your system.
* Download & extract the CLI to the current folder.
* Check for a profile in one of `.profile, .bashrc, .bash_profile, .zshrc` and append `export PATH="<PWD result>:$PATH"`, so you can call 'tx' from any path.
**Note:** You need to restart your terminal for the `PATH` changes to be applied.
### Download from Github Releases (Linux/Mac/Windows)
Another way to install the Transifex CLI is to download
the latest version of the binary from GitHub
[here](https://github.com/transifex/cli/releases).
Choose the binary according to your system, download it and unzip it.
Copy the binary into the location you want and update the `PATH` variable
of your system if necessary.
The other way to install Transifex CLI in the system is to use the code.
Clone the [repository](https://github.com/transifex/cli) and go into the directory
```shell
cd /path/to/transifex/cli
```
### Building from source
The default way to build the binary is
```shell
make build
```
This method requires to have golang in your system. It compiles Transifex CLI and
moves it into the `./bin/` directory of the repository.
If you don't have golang installed, but you have Docker enabled, you can use
the following command:
```shell
make docker-build
```
This will build the binary and it will copy it at `./bin/` in the repository.
## Migrating from older versions of the client
The current version of the client maintains backwards compatibility for the `tx push`
and `tx pull` commands. So, if you have a CI setup that uses them, you should not have
to change anything. However, some things need to be different in the configuration files:
The section headers in `.tx/config` need to be different to also store the organization slug.
So after the migration `<project>.<resource>` should become `o:<org>:p:<proj>:r:<res>`.
In case something fails during this process, we will provide a message with the failed
migrated resource so that you can identify and change the section header manually.
You will be prompted for an API token in case you are using a username/password pair in
your `~/.transifexrc` file or if you are not using one.
If you are migrating an existing software project from an older version of the Transifex
client, you need to run:
```
tx migrate
```
This will take care of all the changes and create a back up file of the original config
in the same folder as `config_yyyymmddhhss.bak` before we start the migration process.
### Differences With the Previous Version
The two clients have some distinct differences when looking under the hood.
The new client is using Go instead of Python
* for speed and
* for the ability to produce binary files
for multiple platforms.
Additionally, client is using APIv3 instead of APIv2 because
* it is faster (calls occur asynchronously and you don't have to wait
for parsing to finish) and
* APIv2 is getting deprecated.
`Init`
The new client's init command creates the `.tx` folder in the current path,
and the config file with the following content which is required for the configuration:
```shell
[main]
host=https://www.transifex.com
```
In case there is already a `.tx/config` file in the current directory, the users
will get a prompt that informs them that, if they proceed, the contents of their
`.tx/config` file will be overridden. A `y/n` answer, is needed to proceed or abort.
`Add`
For the previous client, parts of functionality in `tx config` command adds resources
locally.
In the new client, this command is responsible to add a resource in the local config file.
Note that it needs all `organization`, `project` and `resource` slugs in order to build
the resource id for the APIv3.
It will create a new section in the `.tx/config` file for a resource like:
```ini
[o:org_slug:p:project_slug:r:resource_slug]
...
```
`Push`
The differences of the new client, are summarized here:
* resource IDs, can be accepted without the `-r` flag
* when neither `-s/-t` are set, `-s` is assumed
* `--all` flag creates new languages on Transifex if
local files exist for them (on previous client this was the default behavior,
now it needs the `--all` flag)
* without `--all` or `--languages`, the only languages that are considered are
the intersection of local and remote languages
`Pull`
* resource IDs, can be accepted without the `-r` flag
* when neither `-s/-t` are set, `-t` is assumed
* without `--all` or `--languages`, the only languages that are considered are
the intersection of local and remote languages
* `--json` download files (translations) as json files
* `--content_encoding/-e` The encoding of the file. This can be one of the following:
* text (default)
* base64
## Usage
### Initialising a Project
The first thing we need to do is run:
```
tx init
```
This will simply create an empty `.tx/config` file to mark the current folder
as a _Transifex project_. Your directory structure should now look like this:
```
- my_project/
|
+ .tx/
| |
| + config
|
+ locale/
|
+ en.php
```
### Adding Resources to Configuration
We will add the php file as a source language file in our local configuration. The simplest way to do this is with `tx add` which will start an interactive session:
```
The Transifex Client syncs files between your local directory and Transifex.
The mapping configuration between the two is stored in a file called .tx/config
in your current directory. For more information, visit
https://docs.transifex.com/client/config/.
What is the path of the source file? locale/en.php
Next, we’ll need a path expression pointing to the location of the
translation files (whether they exist yet or not) associated with
the source file. You should include <lang> as a
wildcard for the language code.
What is your path extension? locale/<lang>.php
Use the arrow keys to navigate: ↓ ↑ → ← and / toggles search
? Which organization will this resource be part of?:
> Organization 1 (organization-1)
Organization 2 (organization-2)
Organization 3 (organization-3)
Organization 4 (organization-4)
↓ Organization 5 (organization-5)
Use the arrow keys to navigate: ↓ ↑ → ← and / toggles search
? Which project will this resource be part of?:
> Project 1 (project-1)
Use the arrow keys to navigate: ↓ ↑ → ← and / toggles search
? Which is the resource for this file?:
> en.php (en_php)
Create a new resource ()
SUCCESS Your configuration has been saved in '.tx/config'
You can now push and pull content with 'tx push' and 'tx pull'
```
Your `.tx/config` file should look like this:
```ini
[main]
host = https://www.transifex.com
[o:organization-1:p:project-1:r:en_php]
source_file = locale/en.php
file_filter = locale/<lang>.php
type = PHP
```
You can skip steps from the interactive session by adding flags to the `tx add`
command. In fact, you can skip the interactive session entirely if you provide
all the flags:
```
→ tx add \
--file-filter=locale/<lang>.php \
--type=PHP \
--organization=organization-1 \
--project=project-1 \
--resource=en_php \
locale/en.php
```
### Pushing Files to Transifex
`tx push` is used to push language files (usually source language files) from
your machine to Transifex. You will most likely want to do that frequently
during the lifetime of you project when new source strings are introduced or
existing ones are changed. This will make the new strings available to
translators as soon as possible.
The simplest invocation of `tx push` is simply:
```sh
→ tx push
```
This will attempt to push the source file of all local resources that have been
configured with `tx add`.
**Limiting resources:**
You can limit the resources you want to push with:
```sh
→ tx push [RESOURCE_ID]...
```
A resource ID must refer to a resource that has already been configured with
`tx add` and has the form `<project>.<resource>`. So, if the URL of your
resource in Transifex is
`https://www.transifex.com/myorganization/myproject/myresource`, then the
resource ID will be `myproject.myresource`.
> Note: for backwards compatibility with previous versions of the client, you
> can also use the `-r/--resources` flag. You can also use both at the same
> time:
>
> ```sh
> → tx push p1.r1 p1.r2 -r p1.r3,p1.r4
> # Equivalent to
> → tx push p1.r1 p1.r2 p1.r3 p1.r4
> ```
`tx push` will create the resources on Transifex if they are missing.
**Language management:**
By default, the client will push the source file (the file that's being pointed
to by the `source_file` configuration option from `tx add`). If you use the
`-t/--translation` flag, `tx push` will push translation files. This may be
desirable if, for example, you previously pulled translation files with the
`--mode translator` option, translated using an offline translation tool and
now you want to push your work to Transifex, or if you are migrating from
another localization management service to Transifex. If you use both the `-t`
_and_ the `-s/--source` flags, then you will push both the source file and the
translation files.
When you use `-t`, the client will find all local files that match the
`file-filter` configuration option. The files that are found, and their language
codes constitute the _local_ languages. By default, the client will ask the
Transifex API for the languages that are supported by the project you are
pushing to (the _remote_ languages) and will only push languages that are both
_local_ and _remote_ (aka the **intersection** of _local_ and _remote_
languages).
You can use the `-l/--languages` flag to handpick which languages you want to
push. It only makes sense to include _local_ languages with the `-l` flag, ie
languages for which a file exists according to the `file-filter` configuration
option. The client will then push **only** the language files you have
specified. If you specify _local_ languages that are not yet supported by the
remote Transifex project, the client will attempt to add these languages to the
project first. Be careful of this since it may affect your pricing if you are a
paying customer.
```sh
→ tx push -t -l fr,de,pt_BR
```
The `-a/--all` flag will attempt to push **all** _local_ languages to the
remote Transifex project, adding them if necessary. Essentially, `-a` is
equivalent to using `-l` with all the _local_ language codes.
Transifex uses the _ISO/IEC 15897_ standard for language codes (for example
`en_US`). If you use a different format for the _local_ language codes, you can
define a mapping in your configuration file `.tx/config` (later we will offer
the `tx config` command to make editing the configuration more convenient). You
can specify these mappings for all configured resources by adding them to the
`[main]` section or you can specify mappings per resource. The "per-resource"
mappings take precendence. Configuring a language mapping looks like this:
```ini
# ...
[o:myorganization:p:myproject:r:myresource]
source-file = ...
# ...
lang_map = pt_PT: pt-pt, pt_BR: pt-br
```
This means that the _remote_ `pt_PT` language code maps to the _local_ `pt-pt`
language code and the _remote_ `pt_BR` language code maps to the _local_
`pt-br` language code.
The `-l` flag works with both _local_ and _remote_ language codes.
**Skipping pushing older files:**
The default behavior of the `tx push` command is to skip pushing a file when
the remote resource on Transifex has had a change more recently than when the
local file was last edited. To make sure that the local files are pushed even
if they are older than the remote resource, use the `-f/--force` flag.
You can use the `--use-git-timestamps` flag to compare against the last time
the local files were *committed* to the local git repository instead of the
last modification time in the filesystem. This can be useful in cases where you
have just cloned a repository or pulled a branch. In this case, the filesystem
modification time will reflect the time you pulled and not the time the file
was edited by an actual person. If you use the `--use-git-timestamps` flag and
no information about a local git repository can be found, then the client will
default to taking the filesystem timestamp into account.
**Other flags:**
- `--xliff`: Push xliff files instead of regular ones. The files must be
located **in the same place** as indicated by the `file-filter` configuration
option, but with the added `.xlf` suffix (`tx pull`ing with the `--xliff`
option will put xliff files in the correct positions so you will probably not
have to do this by hand)
- `--branch`: Using this flag, you can access copies of the regular remote
resource that are tied to the provided branch. So if `tx push proj.res`
pushes to the `https://www.transifex.com/org/proj/res` resource, then `tx
push --branch foo proj.res` will push to the
`https://www.transifex.com/org/proj/foo--res` resource. This way you can
separate the localization effort across different branches. If you supply an
empty string as the branch (`--branch ''`), then the client will attempt to
figure out the currently active branch in the local git repository. For
example:
```sh
→ git checkout -b new_feature
→ # Edit some source code files
→ # Extract source strings into language file
→ tx push --branch 'new_feature' myproject.myresource
→ # Or
→ tx push --branch '' myproject.myresource
```
This way, the "regular"
`https://www.transifex.com/myorganization/myproject/myresource` resource will
not be affected by the changes you did to the source strings and the
localization effort can be done in parallel on the
`https://www.transifex.com/myorganization/myproject/new_feature--myresource`
resource.
- `--skip`: Normally, if an upload fails, the client will abort. This may not
be desirable if most uploads are expected to succeed. For example, the reason
of the failed upload may be a syntax error in _one_ of the language files. If
you set the `--skip` flag and an upload fails, then the client will simply
print a warning and move on to the next language file.
### Pulling Files from Transifex
`tx pull` is used to pull language files (usually translation language files) from
Transifex to your machine. Most likely, you will do this regularly when you want to
incorporate newly available translations from Transifex into it.
The simplest invocation of `tx pull` is simply:
```shell
→ tx pull
```
This will attempt to pull the translation files of all local resources that have been
configured with `tx add`.
**Limiting resources:**
You can limit the resources you want to pull with:
```shell
→ tx pull [RESOURCE_ID]...
```
As stated in the `tx push` section, a resource ID must refer to a resource that has
already been configured with `tx add` and has the form `<project>.<resource>`.
> Note: for backwards compatibility with previous versions of the client, you
> can also use the `-r/--resources` flag. You can also use both at the same
> time:
>
> ```sh
> → tx pull p1.r1 p1.r2 -r p1.r3,p1.r4
> # Equivalent to
> → tx pull p1.r1 p1.r2 p1.r3 p1.r4
> ```
**Language management:**
By default, the client will pull the translation files of the existing files in the paths
that are defined in the `file_filter` configuration option from `tx add`.
For instance, if the directory structure looks like this:
```
- my_project/
|
+ .tx/
| |
| + config
|
+ locale/
|
+ en.php
```
and the `.tx/config` contains:
```shell
source_file = locale/en.php
file_filter = locale/<lang>.php
```
If you use the `-s/--source` flag, `tx pull` will pull the source file that is
pointed from the `source_file` option of the config file.
If you use both the `-t/--translation` _and_ the `-s/--source` flags,
then you will pull both the source file, and the translation files.
Then the client will try to search for any existing language file located
at the `locale/<lang>` path (where `<lang>` is the language code) and will
try to update it.
i.e `locale/el.php`, `locale/fr.php` etc
In case that there aren't any translation files, like in the structure above,
then you must either use the `-l/--language` or the `-a/--all` flag.
Use the `-l/--languages` flag to handpick which languages you want to
pull. It only makes sense to include _remote_ languages with the `-l` flag, ie
languages for which a file does not exist according to the `file_filter`
configuration option. The client will then pull **only** the language
files you have specified:
```shell
tx pull -l el,fr,nl
```
> Note:
> The languages that are defined with the -l/--language flag
> should belong to the project for the client to download them.
The `-a/--all` flag will attempt to pull **all** languages from the
remote Transifex project. Essentially, `-a` is equivalent to using
`-l` with all the project language codes.
As stated before, Transifex uses the _ISO/IEC 15897_ standard for
language codes. If you use a different format for the _local_ language
codes, you can define a mapping in your configuration file `.tx/config`.
You can specify these mappings for all configured resources by adding them
to the `[main]` section or you can specify mappings per resource.
The "per-resource" mappings take precendence. Configuring a language mapping
looks like this:
```ini
# ...
[o:myorganization:p:myproject:r:myresource]
source-file = ...
# ...
lang_map = pt_PT: pt-pt, pt_BR: pt-br
```
This means that the _remote_ `pt_PT` language code maps to the _local_ `pt-pt`
language code and the _remote_ `pt_BR` language code maps to the _local_
`pt-br` language code.
The `-l` flag works with _remote_ language codes.
**Skipping pulling older files:**
The default behavior of the `tx pull` command is to skip pulling a file when
a local file on a machine has had a change more recently than when the
remote resource was last edited. To make sure that the remote resources
are pulled even if they are older than the local files, use the `-f/--force` flag.
You can use the `--use-git-timestamps` flag to compare against the last time
the local files were *committed* to the local git repository instead of the
last modification time in the filesystem. This can be useful in cases where you
have just cloned a repository or pulled a branch. In this case, the filesystem
modification time will reflect the time you pulled and not the time the file
was edited by an actual person. If you use the `--use-git-timestamps` flag and
no information about a local git repository can be found, then the client will
default to taking the filesystem timestamp into account.
**Other flags:**
- `--xliff`: Pull xliff files instead of regular ones. The files will be
placed **in the same place** as indicated by the `source-file` and
`file-filter` configuration options, but with the added `.xlf` suffix.
- `--json`: Pull translation files as json instead of regular ones. As above,
the files will be placed **in the same place** as indicated by the `file-filter`
configuration options, but with the added `.json` suffix. Currently, source
files are not supporting json format.
- `--disable-overwrite`: If a file exists do not update it. This is useful
when using `-a/--all` flag and you don't want to change the existing files
but only download other language files.
- `--branch`: Using this flag, you can access copies of the regular remote
resource that are tied to the provided branch. So if `tx pull proj.res`
pulls from the `https://www.transifex.com/org/proj/res` resource, then `tx
pull --branch foo proj.res` will pull from the
`https://www.transifex.com/org/proj/foo--res` resource. This way you can
separate the localization effort across different branches. If you supply an
empty string as the branch (`--branch ''`), then the client will attempt to
figure out the currently active branch in the local git repository. For
example:
```sh
→ git checkout new_feature
→ # Get updated files for this branch
→ tx pull --branch 'new_feature' myproject.myresource
→ # Or
→ tx pull --branch '' myproject.myresource
```
This way, the "regular"
`https://www.transifex.com/myorganization/myproject/myresource` resource will
not be affected by the changes one did, and the localization effort can be done
in parallel on the
`https://www.transifex.com/myorganization/myproject/new_feature--myresource`
resource.
- `--skip`: Normally, if a download fails, the client will abort. This may not
be desirable if most downloads are expected to succeed. For example, the reason
of the failed download may be a syntax error in _one_ of the language files. If
you set the `--skip` flag and an upload fails, then the client will simply
print a warning and move on to the next language file.
- `--minimum_perc=MINIMUM_PERC` Specify the minimum translation completion threshold required in order for a file to be downloaded.
### Removing resources from Transifex
The tx delete command lets you delete a resource that's in your `config` file and on Transifex.
To delete a resource, use the following command:
```
tx delete <project_slug>.<resource_slug>
```
To delete all resources in a specific project at once, instead of referring to a specific resource_slug, you can use the asterisk character as follows:
```
tx delete project_slug.*
or
tx delete project_slug.\*
```
> Note: for backwards compatibility with previous versions of the client, you
> can also use the `-r/--resources` flag. You can also use both at the same
> time:
>
> ```sh
> tx delete -r <project_slug>.<resource_slug> ....
> ```
**Other flags:**
- `--skip`: Normally, if a delete fails, the client will abort. This may not
be desirable if most deletes are expected to succeed. For example, the reason
of the failed delete may be a a resource that has translated content. If
you set the `-s/--skip` flag and an delete fails, then the client will simply
print a warning and move on to the next resource.
- `--force`: In case you want to proceed to a deletion even if resources have
translations use the `-f/--force` flag.
- `--branch`: In case you want to delete a resource's branch that is on Transifex.
If you supply an empty string as the branch (`--branch ''`), then the client
will attempt to figure out the currently active branch in the local git repository.
### Getting the local status of the project
The status command displays the existing configuration in a human readable format. It lists all resources that have been initialized under the local repo/directory and all their associated translation files:
```
tx status
myproject -> default (1 of 1)
Translation Files:
- en: po/smolt.pot (source)
- ar: po/ar.po
- as: po/as.po
- bg: po/bg.po
- bn_IN: po/bn_IN.p
...
```
To get the status of specific resources just add the resources you want in your command:
```
tx status <project_slug>.<resource_slug> ....
```
> Note: for backwards compatibility with previous versions of the client, you
> can also use the `-r/--resources` flag. You can also use both at the same
> time:
>
> ```sh
> tx status -r <project_slug>.<resource_slug> ....
> ```
### Updating the CLI app
The `tx update` command provide's a way to self update the application wihtout going to Github releases page.
```
tx update
```
**Flags:**
- `--check`: Check if there is a new release. Nothing gets updated.
- `--no-interactive`: Proceed to update if there is a newer version without seeing the confirmation prompt.
- `--debug`: Enable logging for the binary update process.
# License
Licensed under Apache License 2.0, see [LICENSE](LICENSE) file.

35
make.bat Normal file
View File

@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd

3
requirements.txt Normal file
View File

@ -0,0 +1,3 @@
myst-parser==0.17.2
sphinx-intl==2.0.1
sphinx-rtd-theme==1.0.0

76
source/conf.py Normal file
View File

@ -0,0 +1,76 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
source_suffix = ['.rst', '.md']
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'ringtools'
copyright = '2022, Djuri Baars'
author = 'Djuri Baars'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx_rtd_theme',
"myst_parser",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
#language = 'en,nl,de'
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
# 'logo_only': False,
# 'display_version': True,
# 'prev_next_buttons_location': 'bottom',
# 'style_external_links': False,
# 'vcs_pageview_mode': '',
# # Toc options
'collapse_navigation': True,
'sticky_navigation': True,
# 'navigation_depth': 4,
# 'includehidden': True,
# 'titles_only': False
}
html_static_path = ['_static']

13
source/faq.md Normal file
View File

@ -0,0 +1,13 @@
# Frequently asked questions
### How many sats do I need to open a channel when joining a ring?
Since you also need some sats to open, close and perhaps reopen a channel it is recommended to have at least 40.000 sats in your wallet on top of the amount of sats you need to open your channel. That means if you participate in a 500.000 sats ring, have 540.000 sats in your on-chain wallet.&#x20;
### Why is the channel size of my channel lower than the amount I entered when opening?
In the channel overview of Umbrel, after opening the commit fee is deducted from the full capacity. This is better explained as a reservation of the on-chain fees when the channel is closed unilaterally.
### Why can't I spend or receive the full amount visible on one side of a channel?
A fixed amount (often 1% by default) is reserved on each side on the channel in the case you need to force-close a channel.&#x20;

BIN
source/img/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 187 KiB

48
source/index.md Normal file
View File

@ -0,0 +1,48 @@
# RingTools
````{toctree}
:caption: RingTools-CLI
:hidden: true
ringtools-cli.md
````
````{toctree}
---
caption: RingTools-web
hidden: true
maxdepth: 1
---
ringtools-web-public.md
````
````{toctree}
---
caption: Telegram-bot
maxdepth: 1
hidden: true
---
tg/overview.md
tg/participate.md
tg/convenience.md
tg/admins.md
````
````{toctree}
---
caption: Rings of Fire
maxdepth: 1
hidden: true
---
faq.md
````
````{toctree}
---
caption: Links
maxdepth: 1
hidden: true
---
Satoshi Radio <https://t.me/satoshiradio>
Satoshi Radio ROF <https://t.me/SatoshiRadioROF>
Connect the World: <https://t.me/connect_the_world>
````
A set of tools which help to set up and manage Rings of Fire, a concept of Bitcoin Lightning Networks.
![Screenshot](screenshots/web-main.png)

22
source/ringtools-cli.md Normal file
View File

@ -0,0 +1,22 @@
# Installation and usage
Check out the repo of [@StijnBTC/Ringtools](https://github.com/StijnBTC/Ringtools) for the most recent usage instructions.
## Installation
1. Open your SSH client and log into your node
2. Update pip to be sure `pip3 install --upgrade pip`
3. Clone this repository `git clone https://github.com/StijnBTC/Ringtools`
4. Navigate to the right folder `cd Ringtools`
5. Install the requirements `pip3 install -r requirements.txt`
## Usage
1. Put all public keys and telegram usernames, separated with a comma in `pubkeys.txt`
2. Run `checkring` functionality with write to create channels.txt `python3 ringtools.py check --write-channels`
3. Run Ringtools `python3 ringtools.py -f -l status` (When you're ready, hit Ctrl+C)
## Instructions for use with c-lightning
RingTools-CLI uses LND by default. To use c-lightning add `--client cl` as argument.
If you don't have the RPC unix at the default location use the ` --clrpc /path/to/lightning-rpc` argument.
The channel format is different when using C-lightning, but if you use the `pubkeys.txt` file this should not matter.

24
source/ringtools-web-public.md Normal file
View File

@ -0,0 +1,24 @@
# Public instance
There is a public instance available at [rof.tools](https://rof.tools). Although it does have channels, it is probably not part of the Ring of Fire you are leading or participating in so gossip might be slower.
## Manual import node information from Cheeserobot
- Make sure Cheeserobot is in the ring channel
- Say `/groupnodes@cheeserobot`
![Screenshot](screenshots/groupnodes-cheeserobot.png)
- Download the `.csv` file
- Open it in a text editor (don't open it in a spreadsheet like Excel or Numbers)
- Select all and copy to clipboard, including headers.
- Go to the settings page of [Ringtools-Web](https://rof.tools/settings)
- Paste the clipboard contents to the Import area.
![Screenshot](screenshots/import-settings.png)
- Press `Import Groupnodes` button.
- You should now see the node information on the right side.
- Set a Ringname
- Click `Save Ring Settings` to persist to the browsers localstorage
- You are now ready to use the `Design` and `Watch` parts of `Ringtools-Web`

BIN
source/screenshots/admin-permissions-small.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
source/screenshots/admin-permissions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

BIN
source/screenshots/country_consent.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
source/screenshots/groupnodes-cheeserobot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
source/screenshots/import-settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

BIN
source/screenshots/participate_country_funded.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

BIN
source/screenshots/pollcountries.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
source/screenshots/remembernode.webm Normal file
View File

Binary file not shown.

BIN
source/screenshots/setcountry.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
source/screenshots/web-main-backup.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 122 KiB

BIN
source/screenshots/web-main.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 122 KiB

50
source/tg/admins.md Normal file
View File

@ -0,0 +1,50 @@
# For admins
## Ring Wizard
The ring wizard automates the channel setup, just use `/start_ring_wizard` and follow the steps. Make sure you set all necessary permissions correctly.
<center>
![Required admin permissions](/screenshots/admin-permissions-small.png)
</center>
## Manually set up Telegram channel
1. Create channel group, set name and invite [@ringtools_bot](https://t.me/ringtools_bot).
2. Set name and size:
- `/set_name [RingName]` (e.g.) `/set_name #SRROF_1Msats_21stRING`
- `/set_size [RingSize]` (e.g.) `/set_size 1000000`
3. Get channel logo: `/update_logo` (It should automatically detect size and number from the Ring Name).
4. Create ringleader poll: `/poll_ringleader`
5. Set autoclean (optional):
- `/set_autoclean cmd true` (Removes bot commands by others after 1 minute)
- `/set_autoclean self true` (Removes bot response after 1 minute)
6. (Optional) Post welcome message `/post_message welcome`
7. (Optional) Set user greeting `/set_greeting`
8. (Optional) Enable user greeting `/ring_greet true 900` (900 seconds is 15 minutes)
9. (Optional) Change ring group channel name `/update_name`
## Opening channels
1. (Optional) reorder participants with `/set_order [PubKeysContents]` (after reordering, download pubkeys.txt from [ringtools-web](https://rof.tools))
2. Post channel opening instructions message `/post_message opening_channels`
2. Share ring visual from the watch page of [ringtools-web](https://rof.tools)
3. Let know who has to open with who `/ring_channels long`
4. Set the channel message to auto update with `/set_ring_mode opening_channels`
5. Get ring visual `/ring_visual`
## Choose ringleader and post balancing instructions
1. Reorder participants so the ringleader will be at the bottom with `/set_order [PubKeysContents]` (after reordering, download pubkeys.txt from [ringtools-web](https://rof.tools))
2. Make sure the ringleader has set a username and said `/start` in a DM to [@ringtools_bot](https://t.me/ringtools_bot), and that [@ringtools_bot](https://t.me/ringtools_bot) has the permission to promote other users.
3. Make someone ringleader `/set_ringleader @ringleader`
4. Post the igniter instructions message `/post_message igniter`
5. (Optional) generate the `igniter.conf` file `/get_file igniterconf`
## After balancing
1. Post the fee information message `/post_message fee_info`
2. Set the ring to balanced `/set_ring_mode balanced`
3. Update the ring logo `/update_logo`
4. Post the balanced message `/post_message balanced`

37
source/tg/convenience.md Normal file
View File

@ -0,0 +1,37 @@
# Convenience features
All convenience features are optional to use. The bot will not announce your registration in public channels.
## Remember country
You can say `/set_country [2-letter country code]` in a DM to [@ringtools_bot](https://t.me/ringtools_bot), so you don't have type this every time you join a ring.
<center>
![Set country](/screenshots/setcountry.png)
</center>
## Show flag in participation list
After setting your country in a DM with [@ringtools_bot](https://t.me/ringtools_bot) you can show the country you are from in the participation lists, you can enable visibility with `/country_visible`. Saying it again will toggle it off again.
<center>
![Country visibility](/screenshots/country_consent.png)
![Flag in participation system](/screenshots/pollcountries.jpg)
</center>
## Remember (multiple) nodes
You can register your node after verification so you don't have to type your public key after saying `/participate`. Say `/add_node` in a DM to [@ringtools_bot](https://t.me/ringtools_bot) and follow the wizard.
Next time you do `/participate` in a ring you can select your node using buttons, if you have multiple nodes then multiple buttons will be shown.
See the video below too see it in action.
<video width="100%" height="400" controls>
<source src="/screenshots/remembernode.webm" type="video/webm">
Your browser does not support the video tag.
</video>

66
source/tg/overview.md Normal file
View File

@ -0,0 +1,66 @@
# Overview
The RingTools Telegram-bot is currently main supporting the Satoshi Radio / Connect the World Rings of Fire and therefore mainly suited as support for the process they are using. It is still is early development so commands might change.
## Public commands
````text
/ping - Check if I'm alive.
/donate [Sats] [Message] - Donate to Ringtools-Web Development
/fullnodeaddress [PubKey] - Get full address of lightning node
/nodeinfo [PubKey] - Get Lightning node info
/chaninfo [ChannelID] - Get Lightning channel info
/set_country [CountryCode] - Set your country to #connect_the_world (e.g. NL or US)
/add_node - Register node (see convience features)
/country_visible - Make country visible in ring participation polls.
````
## Ring-group commands
### For all ring participants
````text
/ringurl - Get ring-specific link for Ringtools-Web
/ring_channels - Get overview of channels
/node_overview_csv - Export Groupnodes CSV
/node_overview - Ring participant overview
````
### For individual ring participants
````text
/participate [PubKey] - Join this ring (if you don't have any channels,
use your full node URI)
/unparticipate - Leave this ring
/set_funded - Confirm you are funded
/set_country [CountryCode] - Set your country to #connect_the_world (e.g. NL or US)
/unparticipate - Leave this ring
/get_tz - Get overview of timezones of all participants
/get_file [igniterconf] - Get igniter.conf file (only when all channels are opened)
````
### For masters of ceremony
````text
/set_name [RingName] - Get Lightning channel info
/set_size [RingSize] - Get Lightning channel info
/import_csv [FileContents] - Import Groupnodes CSV from Cheeserobot
/set_ring_mode [mode] - Set ring mode (e.g. opening_channels)
/ring_group_logo [Size] [Nr] - Create a ring group logo (admins only)
last parameters are balanced and country
/set_order [PubKeysContents] - Reorder participants (using pubkeys.txt export
from Ringtools-Web)
/set_ringleader - Set Ringleader of the ring
/post_message [welcome|channels] - Post welcome/channel opening message
/view_channel_settings - View channel settings
/set_autoclean [cmd|self] [true] - Change autoclean settings
/set_greeting [text] - Set new user message
/ring_greet [true/false] [cleanDelay] - Enable/disable new user greeting
/update_name - Update ring name
/ring_visual - Get ring visual (same as on rof.tools)
/update_logo - Update ring group logo
````
### Poll commands
````diff
- /poll_ring [RingName] [MaxPpl] - Create poll to join a ring, old format (admins only)
/poll_ring_v2 [RingName] [MaxPpl] - Create poll to join a ring (admins only)
/poll_ringleader - Create poll to become ringleader (admins only)
/admin_close_poll - Force close poll
````

11
source/tg/participate.md Normal file
View File

@ -0,0 +1,11 @@
# Participants
## Participate in ring
1. Signal your participation with `/participate [PubKey]` (e.g. `/participate 0380b3dbdf090cacee19eb4dc7a82630bd3de8b12608dd7bee971fb3cd2a5ae2fc`)
2. Set your country with `/set_country [Country]` using the 2-letter country code (e.g. `/set_country nl`)
3. Let know if/when you have the funds to open the channel `/set_funded true`
<center>
![Participate screenshot](/screenshots/participate_country_funded.png)
</center>

1
source/web/index.md Normal file
View File

@ -0,0 +1 @@
# Hello

60
source/web/local-install.md Normal file
View File

@ -0,0 +1,60 @@
# Local Instance
To use RingTools-web on your own node, you can use the pre-made docker image, build the docker-image yourself or run the components from source.
## Umbrel using docker image
You can run ringtools-web on your umbrel node with the pre-made image:
1) Put the following in a `docker-compose.yml` file on your node:
````YAML
version: "3.7"
services:
ringtoolsweb:
image: ghcr.io/ringtools/ringtools-web:latest
ports:
- "7464:7464"
networks:
- umbrel
environment:
- PORT=7464
- LND_REST_API_WS=wss://10.21.21.9:8080
- LND_REST_API=https://10.21.21.9:8080
- MACAROON_FILE=/lnd/readonly.macaroon
- TLS_CERT_FILE=/lnd/tls.cert
volumes:
- /home/umbrel/umbrel/lnd/tls.cert:/lnd/tls.cert:ro
- /home/umbrel/umbrel/lnd/data/chain/bitcoin/mainnet/readonly.macaroon:/lnd/readonly.macaroon:ro
networks:
umbrel:
external: true
name: umbrel_main_network
````
2. Run it with `docker-compose up -d`
3. Your local ringtools-web instance should be available at http://umbrel.local:7464
4. To stop it, run `docker-compose stop`
If you prefer to build your own docker image, the source is available on [Github](https://github.com/ringtools/ringtools-web-docker)
## Run from source
### Server (backend)
1. Clone the server repository: `git clone https://github.com/ringtools/ringtools-server-ts`
2. Set up the `.env` tailored to your environment (see `.env.sample` for all options)
3. Install dependencies `yarn install`
4. Run the server `yarn start`
5. The backend should be available at `http://localhost:7464` (Unless you set a different value for the `PORT` environment variable)
### Frontend
1. Clone the server repository: `git clone https://github.com/ringtools/ringtools-web-v2.git`
2. If necessary, set up the `.env` tailored to your environment (see `.env.defaults` for all options) The default value works if you compile the frontend and serve it using the `server`.
3. Install dependencies `yarn install`
4. Run the server `yarn start`
5. The backend should be available at `http://localhost:4200`
**Note**: You might need to modify the CORS settings on the server to make it work on localhost.