Skip to content

Commit f0449f3

Browse files
Jared-dzJared-dz
authored
Language support, and troubleshooting additions (#156)
* Add multi-language infrastructure and Spanish translations - Add mkdocs-static-i18n plugin to mkdocs.yml with support for en, zh, ja, ko, pt, es, fr, it - Update mkdocs build workflow to install mkdocs-static-i18n - Add translate.yml GitHub Actions workflow to auto-translate docs on push using Claude API - Add scripts/translate.py for automated translation via Anthropic SDK - Add Spanish (.es.md) translations for all 23 documentation pages * Add translations for zh, pt, ko, ja, it, fr (23 pages each) Adds 138 translated documentation files covering all 23 pages in six languages: Chinese (zh), Portuguese (pt), Korean (ko), Japanese (ja), Italian (it), and French (fr). * add warning * add retramsit troublshooting * Update Validator Multicast Connection.md * Update Validator Multicast Connection.md * Update publisher-check-dashboard.png * Update Validator Multicast Connection.md * Update Validator Multicast Connection.md * Refine Validator Multicast Connection.md with additional details and clarifications * update lang selector
1 parent de6ae0d commit f0449f3

426 files changed

Lines changed: 287024 additions & 13 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/translate.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Auto-translate docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**.md'
8+
9+
jobs:
10+
translate:
11+
runs-on: ubuntu-latest
12+
# Prevent infinite loop: skip when the bot itself pushes translations
13+
if: github.event.head_commit.author.name != 'github-actions[bot]'
14+
permissions:
15+
contents: write
16+
steps:
17+
- uses: actions/checkout@v4
18+
with:
19+
fetch-depth: 2
20+
21+
- uses: actions/setup-python@v5
22+
with:
23+
python-version: '3.12'
24+
25+
- run: pip install anthropic
26+
27+
- name: Find changed source docs
28+
id: changed
29+
run: |
30+
BASE=$(git rev-parse HEAD~1 2>/dev/null || git hash-object -t tree /dev/null)
31+
# Only source .md files — exclude already-translated ones (e.g. index.es.md)
32+
CHANGED=$(git diff --name-only "$BASE" HEAD -- docs/ \
33+
| grep '\.md$' \
34+
| grep -vE '\.[a-z]{2,3}\.md$' \
35+
|| true)
36+
echo "Source files changed:"
37+
echo "$CHANGED"
38+
{
39+
echo "files<<EOF"
40+
echo "$CHANGED"
41+
echo "EOF"
42+
} >> "$GITHUB_OUTPUT"
43+
44+
- name: Translate
45+
if: steps.changed.outputs.files != ''
46+
env:
47+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
48+
CHANGED_FILES: ${{ steps.changed.outputs.files }}
49+
LANGUAGES: "zh,ja,ko,pt,es,fr,it"
50+
run: python scripts/translate.py
51+
52+
- name: Commit translations
53+
if: steps.changed.outputs.files != ''
54+
run: |
55+
git config user.name "github-actions[bot]"
56+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
57+
git add docs/
58+
git diff --cached --quiet || git commit -m "chore: auto-translate docs"
59+
git push

‎README.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
1-
# docs-demo
1+
# Malbec Labs Docs
2+
3+
## Local development
4+
5+
Install the required plugin so `mkdocs serve` works:
6+
7+
```bash
8+
pip install mkdocs-static-i18n
9+
```
10+
11+
Then run:
12+
13+
```bash
14+
mkdocs serve
15+
```

‎docs/DZ Mainnet-beta Connection.es.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Conexión de Validador a Mainnet-Beta en modo IBRL
2+
!!! warning "This translation was generated using artificial intelligence and has not been reviewed by a human translator. It may contain inaccuracies or errors and should not be relied upon."
3+
4+
!!! warning "Al conectarme a DoubleZero acepto los [Términos de Servicio de DoubleZero](https://doublezero.xyz/terms-protocol)"
5+
6+
7+
8+
### Conectando a Mainnet-Beta en modo IBRL
9+
10+
!!! Note inline end
11+
El modo IBRL no requiere reiniciar los clientes de validadores, ya que usa su dirección IP pública existente.
12+
13+
Los Validadores Mainnet de Solana completarán la conexión a DoubleZero Mainnet-beta, que se detalla en esta página.
14+
15+
Cada validador Solana tiene su propio **keypair de identidad**; de él se extrae la clave pública conocida como el **node ID**. Esta es la huella digital única del validador en la red Solana.
16+
17+
Con el DoubleZeroID y el node ID identificados, demostrará la propiedad de su máquina. Esto se hace creando un mensaje que incluye el DoubleZeroID firmado con la clave de identidad del validador. La firma criptográfica resultante sirve como prueba verificable de que controla el validador.
18+
19+
Finalmente, enviará una **solicitud de conexión a DoubleZero**. Esta solicitud comunica: *"Aquí está mi identidad, aquí está la prueba de propiedad y aquí está cómo pretendo conectarme."* DoubleZero valida esta información, acepta la prueba y provisiona acceso a la red para el validador en DoubleZero.
20+
21+
Esta guía permite que 1 Validador Primario se registre a sí mismo, y hasta 3 máquinas de respaldo/failover al mismo tiempo.
22+
23+
## Requisitos Previos
24+
25+
- CLI de Solana instalada y en $PATH
26+
- Para validadores: Permiso para acceder al archivo keypair de identidad del validador (por ejemplo, validator-keypair.json) bajo el usuario sol
27+
- Para validadores: Verificar que la clave de identidad del validador Solana que se conecta tiene al menos 1 SOL
28+
- Las reglas del firewall permiten conexiones salientes para DoubleZero y Solana RPC según sea necesario, incluyendo GRE (ip proto 47) y BGP (169.254.0.0/16 en tcp/179)
29+
30+
!!! info
31+
El ID del Validador se verificará contra el gossip de Solana para determinar la IP objetivo. La IP objetivo y el ID DoubleZero se utilizarán luego para abrir un túnel GRE entre su máquina y el Dispositivo DoubleZero objetivo.
32+
33+
Considere: En el caso en que tenga un ID junk y un ID Primario en la misma IP, solo el ID Primario se usará en el registro de la máquina. Esto se debe a que el ID junk no aparecerá en el gossip y, por lo tanto, no puede usarse para verificar la IP de la máquina objetivo.
34+
35+
## 1. Configuración del Entorno
36+
37+
Siga las instrucciones de [configuración](setup.md) antes de continuar.
38+
39+
El último paso en la configuración fue desconectarse de la red. Esto es para asegurar que solo un túnel esté abierto en su máquina hacia DoubleZero, y que ese túnel esté en la red correcta.
40+
41+
<div data-wizard-step="mainnet-env-config" markdown>
42+
43+
Para configurar el CLI DoubleZero (`doublezero`) y el daemon (`doublezerod`) para conectarse a **DoubleZero mainnet-beta**:
44+
```bash
45+
DESIRED_DOUBLEZERO_ENV=mainnet-beta \
46+
&& sudo mkdir -p /etc/systemd/system/doublezerod.service.d \
47+
&& echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \
48+
&& sudo systemctl daemon-reload \
49+
&& sudo systemctl restart doublezerod \
50+
&& doublezero config set --env $DESIRED_DOUBLEZERO_ENV > /dev/null \
51+
&& echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV"
52+
```
53+
54+
Debería ver la siguiente salida:
55+
`
56+
✅ doublezerod configured for environment mainnet-beta
57+
`
58+
59+
Después de aproximadamente 30 segundos verá los dispositivos DoubleZero disponibles:
60+
61+
```bash
62+
doublezero latency
63+
```
64+
65+
</div>
66+
67+
## 2. Abrir el puerto 44880
68+
69+
Los usuarios necesitan abrir el puerto 44880 para utilizar algunas [funciones de enrutamiento](https://github.com/malbeclabs/doublezero/blob/main/rfcs/rfc7-client-route-liveness.md).
70+
71+
Para abrir el puerto 44880 puede actualizar IP tables de la siguiente manera:
72+
73+
<div data-wizard-step="firewall-iptables" markdown>
74+
75+
```
76+
sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT
77+
sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT
78+
```
79+
80+
</div>
81+
82+
note los flags `-i doublezero0`, `-o doublezero0` que restringen esta regla únicamente a la interfaz DoubleZero
83+
84+
O UFW de la siguiente manera:
85+
86+
<div data-wizard-step="firewall-ufw" markdown>
87+
88+
```
89+
sudo ufw allow in on doublezero0 to any port 44880 proto udp
90+
sudo ufw allow out on doublezero0 to any port 44880 proto udp
91+
```
92+
93+
</div>
94+
95+
note los flags `in on doublezero0`, `out on doublezero0` que restringen esta regla únicamente a la interfaz DoubleZero
96+
97+
## 3. Atestar la Propiedad del Validador
98+
99+
<div data-wizard-step="mainnet-find-validator" markdown>
100+
101+
Con su Entorno DoubleZero configurado, es hora de atestar la Propiedad de su Validador.
102+
103+
El ID DoubleZero que creó en la [configuración](setup.md) de su validador primario debe usarse en todas las máquinas de respaldo.
104+
105+
El ID en su máquina primaria se puede encontrar con `doublezero address`. El mismo ID debe estar en `~/.config/doublezero/id.json` en todas las máquinas del clúster.
106+
107+
Para lograr esto, primero verificará que la máquina desde la que ejecuta los comandos sea su **Validador Primario** con:
108+
109+
```
110+
doublezero-solana passport find-validator -u mainnet-beta
111+
```
112+
113+
Esto verifica que el validador esté registrado en el gossip y aparezca en el cronograma de líderes.
114+
115+
Salida esperada:
116+
117+
```
118+
Connected to Solana: mainnet
119+
120+
DoubleZero ID: YourDoubleZeroAddress11111111111111111111111111111
121+
Detected public IP: 11.11.11.111
122+
Validator ID: ValidatorIdentity111111111111111111111111111
123+
Gossip IP: 11.11.11.111
124+
In Leader scheduler
125+
✅ This validator can connect as a primary in DoubleZero 🖥️ 💎. It is a leader scheduled validator.
126+
```
127+
128+
!!! info
129+
El mismo flujo de trabajo se usa para una o muchas máquinas.
130+
Para registrar una máquina, excluya los argumentos "--backup-validator-ids" o "backup_ids=" de cualquier comando en esta página.
131+
132+
Ahora, en todas las máquinas de respaldo en las que planea ejecutar su **Validador Primario**, ejecute lo siguiente:
133+
```
134+
doublezero-solana passport find-validator -u mainnet-beta
135+
```
136+
137+
Esta salida es esperada. El nodo de respaldo no puede estar en el cronograma de líderes en el momento de la creación del pase.
138+
139+
</div>
140+
141+
142+
<div data-wizard-step="mainnet-prepare-access" markdown>
143+
144+
### Preparar la Conexión
145+
146+
Ejecute el siguiente comando en la máquina del **Validador Primario**. Esta es la máquina en la que tiene stake activo, que está en el cronograma de líderes con su ID de validador primario en el gossip de Solana en la máquina desde la que ejecuta el comando:
147+
148+
```
149+
doublezero-solana passport prepare-validator-access -u mainnet-beta \
150+
--doublezero-address YourDoubleZeroAddress11111111111111111111111111111 \
151+
--primary-validator-id ValidatorIdentity111111111111111111111111111 \
152+
--backup-validator-ids ValidatorIdentity222222222222222222222222222,ValidatorIdentity33333333333333333333333333,ValidatorIdentity444444444444444444444444444>
153+
```
154+
155+
Note la salida al final de este comando. Es la estructura para el siguiente paso.
156+
157+
</div>
158+
159+
## 4. Generar Firma
160+
161+
<div data-wizard-step="mainnet-sign-message" markdown>
162+
163+
Al final del último paso, recibimos una salida preformateada para `solana sign-offchain-message`.
164+
165+
Desde la salida anterior ejecutaremos este comando en la máquina del **Validador Primario**.
166+
167+
```
168+
solana sign-offchain-message \
169+
service_key=YourDoubleZeroAddress11111111111111111111111111111,backup_ids=ValidatorIdentity222222222222222222222222222,ValidatorIdentity33333333333333333333333333,ValidatorIdentity444444444444444444444444444 \
170+
-k <identity-keypair-file.json>
171+
```
172+
173+
**Salida:**
174+
175+
```
176+
Signature111111rrNykTByK2DgJET3U6MdjSa7xgFivS9AHyhdSG6AbYTeczUNJSjYPwBGqpmNGkoWk9NvS3W7
177+
```
178+
179+
</div>
180+
181+
## 5. Iniciar una Solicitud de Conexión en DoubleZero
182+
183+
<div data-wizard-step="mainnet-request-access" markdown>
184+
185+
Use el comando `request-validator-access` para crear una cuenta en Solana para la solicitud de conexión. El agente Sentinel de DoubleZero detecta la nueva cuenta, valida su identidad y firma, y crea el pase de acceso en DoubleZero para que el servidor pueda establecer una conexión.
186+
187+
Use el node ID, el DoubleZeroID y la firma.
188+
189+
!!! note inline end
190+
En este ejemplo usamos `-k /home/user/.config/solana/id.json` para encontrar la Identidad del validador. Use la ubicación apropiada para su despliegue local.
191+
192+
```
193+
doublezero-solana passport request-validator-access -k <path to keypair> -u mainnet-beta \
194+
--primary-validator-id ValidatorIdentity111111111111111111111111111 \
195+
--backup-validator-ids ValidatorIdentity222222222222222222222222222,ValidatorIdentity33333333333333333333333333,ValidatorIdentity444444444444444444444444444 \
196+
--signature Signature111111rrNykTByK2DgJET3U6MdjSa7xgFivS9AHyhdSG6AbYTeczUNJSjYPwBGqpmNGkoWk9NvS3W7 --doublezero-address YourDoubleZeroAddress11111111111111111111111111111
197+
```
198+
199+
**Salida:**
200+
201+
Esta salida puede usarse para ver la transacción en un explorador Solana. Asegúrese de cambiar el explorador a mainnet. Esta verificación es opcional.
202+
203+
```bash
204+
Request Solana validator access: Transaction22222222VaB8FMqM2wEBXyV5THpKRXWrPtDQxmTjHJHiAWteVYTsc7Gjz4hdXxvYoZXGeHkrEayp
205+
```
206+
207+
Si tiene éxito, DoubleZero registrará el primario con sus respaldos. Ahora puede hacer failover entre las IPs registradas en el pase de acceso. DoubleZero mantendrá la conectividad automáticamente al cambiar a nodos de respaldo registrados de esta manera.
208+
209+
</div>
210+
211+
## 6. Conectarse en modo IBRL
212+
213+
<div data-wizard-step="mainnet-connect-ibrl" markdown>
214+
215+
En el servidor, con el usuario que se conectará a DoubleZero, ejecute el comando `connect` para establecer la conexión a DoubleZero.
216+
217+
```
218+
doublezero connect ibrl
219+
```
220+
221+
Debería ver una salida que indique el aprovisionamiento, como:
222+
223+
```
224+
DoubleZero Service Provisioning
225+
🔗 Start Provisioning User...
226+
Public IP detected: 137.184.101.183 - If you want to use a different IP, you can specify it with `--client-ip x.x.x.x`
227+
🔍 Provisioning User for IP: 137.184.101.183
228+
User account created
229+
Connected to device: nyc-dz001
230+
The user has been successfully activated
231+
Service provisioned with status: ok
232+
✅ User Provisioned
233+
```
234+
Espere un minuto para que el túnel GRE termine de configurarse. Hasta que el túnel GRE esté configurado, su salida de estado puede devolver "down" o "Unknown".
235+
236+
Verifique su conexión:
237+
238+
```bash
239+
doublezero status
240+
```
241+
242+
**Salida:**
243+
!!! note inline end
244+
Examine esta salida. Note que `Tunnel src` y `DoubleZero IP` coinciden con la dirección IPv4 pública de su máquina.
245+
246+
```bash
247+
Tunnel status | Last Session Update | Tunnel Name | Tunnel src | Tunnel dst | Doublezero IP | User Type | Current Device | Lowest Latency Device | Metro | Network
248+
up | 2025-10-20 12:12:55 UTC | doublezero0 | 11.11.11.111 | 12.34.56.789 | 11.11.11.111 | IBRL | ams-dz001 | ✅ ams-dz001 | Amsterdam | mainnet-beta
249+
```
250+
Un estado de `up` significa que está conectado correctamente.
251+
252+
Podrá ver las rutas propagadas por otros usuarios en DoubleZero ejecutando:
253+
254+
```
255+
ip route
256+
```
257+
258+
</div>
259+
260+
### Siguiente Paso: Publicar Shreds mediante Multicast
261+
262+
Si ha completado esta configuración y planea publicar shreds mediante multicast, continúe a la [siguiente página](Validator%20Multicast%20Connection.md).

0 commit comments

Comments
 (0)