Get best of the week

Organisasi dokumentasi dan terjemahan, misalnya, iondv. kerangka


Seperti banyak tim yang mengembangkan produk besar, ketika mengembangkan kerangka kerja open source untuk pembuatan visual aplikasi web iondv.framework , tugasnya adalah mendokumentasikan kemampuan sistem. Pertama untuk Anda dan karyawan baru. Lalu untuk pengguna. Dan saat ini, dokumentasi merupakan sarana penting untuk mempromosikan produk. Dan meskipun telah ada perubahan baru-baru ini terhadap materi media (tutorial video), dokumentasi tetap penting.


Kami beralih dari wiki ke gitlab ke dokumentasi terstruktur dan tersinkronisasi dalam dua bahasa dalam bentuk file penurunan harga yang diterbitkan dalam repositori github. Jadi kami memulai transisi ke bundel github + Weblate + readTheDocs. Karena ada beberapa artikel tentang ini di Habré - di bawah ini tentang kesalahan, kesulitan dan pengalaman kami dalam menyiapkan terjemahan proyek sumber terbuka.



wiki ? . - . — . — .


markdown — wiki docs ru en. . - jira — , . , .


:


  • ;
  • , git markdown — ;
  • , — ;
  • ;
  • .

, http://readthedocs.org/ — . Python ( node.js) " " . : — sphinx-doc.org. , readthedocs , .


, markdown – , , . reStructuredText.


, . :



Godot Engine:



. , , , , .



markdown reStructuredText. – readthedocs.


iondv/docs-l10n git submodule add https://github.com/iondv/docs-ru. . translation, master . Reathedocs master .


sphinx. . .


latex_elements , utf8, readthedocs .


latex_elements = {
    'preamble': '\\usepackage[utf8]{inputenc}',
    'babel': '\\usepackage[russian]{babel}',
    'cmappkg': '\\usepackage{cmap}',
    'fontenc': '\\usepackage[T1,T2A]{fontenc}',
    'utf8extra':'\\DeclareUnicodeCharacter{00A0}{\\nobreakspace}',
}

gettext_compact=True, False – Weblate . True – , . , Weblate .


docs-ru, docs-l10n , .


translation.


. , () , Weblate .


(gettext_compact=False), , . – . -, – . , .



. Ubuntu, CentOs . docker service-net, docker network create service-net


-, Weblate – Redis PostgreSql ( )


docker run --name redis -v redis-data:/data \
            --expose 6379 --net service-net \
            --restart unless-stopped -d \
            redis:4-alpine redis-server --appendonly yes

docker run  --name postgres -v postgres-data:/var/lib/postgresql/data \
            --expose 5432 \
            --env "POSTGRES_PASSWORD=123" \
            --env "POSTGRES_USER=iondv" \
            --env "POSTGRES_DATABASE=weblate" \
            --env "POSTGRES_DB=weblate" \
            --env "POSTGRES_HOST=postgres" \
            --env "POSTGRES_PORT=5432" \
            --net service-net --restart unless-stopped -d \
            postgres:11-alpine

Weblate . , , github . .


docker run  --name weblate \
            -v weblate-data:/app/data \
            --expose 8080 \
            --env "DEBUG=True" \
            --env "POSTGRES_PASSWORD=123" \
            --env "POSTGRES_USER=iondv" \
            --env "POSTGRES_DATABASE=weblate" \
            --env "POSTGRES_DB=weblate" \
            --env "POSTGRES_HOST=postgres" \
            --env "POSTGRES_PORT=5432" \
            --env "REDIS_HOST=redis" \
            --env "REDIS_PORT=6379" \
            --env "WEBLATE_EMAIL_HOST=smtp.yandex.ru" \
            --env "WEBLATE_EMAIL_PORT=465" \
            --env "WEBLATE_EMAIL_USE_TLS=True" \
            --env "WEBLATE_EMAIL_HOST_USER=weblate@YOUR_HOST.com" \
            --env "WEBLATE_EMAIL_HOST_PASSWORD=123" \
            --env "WEBLATE_SERVER_EMAIL=weblate@ YOUR_HOST.com" \
            --env "WEBLATE_DEFAULT_FROM_EMAIL=weblate@ YOUR_HOST.com" \
            --env "WEBLATE_ADMIN_PASSWORD=123" \
            --env "WEBLATE_ADMIN_NAME=IONDV Weblate Admin" \
            --env "WEBLATE_ADMIN_EMAIL=weblate@YOUR_HOST.com" \
            --env "WEBLATE_DEBUG=false" \
            --env "WEBLATE_LOGLEVEL=DEBUG" \
            --env "WEBLATE_SITE_TITLE=IONDV.Doc translation" \
            --env "WEBLATE_ALLOWED_HOSTS=weblate.YOUR_HOST.com" \
            --env "WEBLATE_REGISTRATION_OPEN=1" \
            --env "WEBLATE_REQUIRE_LOGIN=0" \
            --env "WEBLATE_TIME_ZONE=Asia/Vladivostok" \
            --env "TZ=Asia/Vladivostok" \
            --net service-net --restart unless-stopped -d \
            weblate/weblate:3.11.2-1

, Weblate 3.10 – , – . 3.11.2-1.


Weblate ssl – nginx, .


/etc/conf.d/weblate.conf


server {
  listen 80;
  server_name weblate.YOURHOST.ru;
  return  301 https://weblate.YOURHOST.ru $request_uri;
}

server {
    listen 443;
    server_name weblate.YOURHOST.ru;
    ssl_stapling on; 
    resolver 8.8.8.8 valid=300s; 
    ssl_certificate      /etc/nginx/cert/YOURHOST.crt;
    ssl_certificate_key  /etc/nginx/cert/YOURHOST.key;
    ssl_dhparam          /etc/nginx/cert/dhparam.pem;

    ssl_session_timeout 10m;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers kEECDH+AES128:kEECDH:kEDH:-3DES:kRSA+AES128:kEDH+3DES:DES-CBC3-SHA:!RC4:!aNULL:!eNULL:!MD5:!EXPORT:!LOW:!SEED:!CAMELLIA:!IDEA:!PSK:!SRP:!SSLv2;
    ssl_prefer_server_ciphers on;
    add_header Strict-Transport-Security "max-age=31536000;";
    add_header Content-Security-Policy-Report-Only "default-src https:; script-src https: 'unsafe-eval' 'unsafe-inline'; style-src https: 'unsafe-inline'; img-src https: data:; font-src https: data:; report-uri /csp-report";

    location / {
        proxy_pass http://weblate:8080;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-NginX-Proxy true;
        proxy_ssl_session_reuse off;
        proxy_set_header Host $http_host;
        proxy_redirect off;
    }
    access_log /var/log/nginx/weblate.access.log;
    error_log /var/log/nginx/weblate.error.log error;
}

github, nginx.


nginx


docker run  --name nginx_proxy \
            -v /etc/nginx.conf:/etc/nginx/nginx.conf:ro -v /etc/conf.d:/etc/nginx/conf.d:ro \
            -v /etc/nginx/cert:/etc/nginx/cert:ro -v /var/log/nginx:/var/log/nginx \
            -p "80:80" -p "443:443" --net service-net \
            --env "TZ=Asia/Vladivostok" \
            --restart unless-stopped -d \
            nginx

sphinx


, cron, . sphinx .


Dockerfile


FROM python:3-alpine
RUN apk add --update make && pip install sphinx sphinx_rtd_theme  sphinx-intl
WORKDIR /docs
VOLUME ["/docs"]
CMD []

Dockerfile docker image build -t sphinx:latest .


/workspace/docs-l10n — docs-ru , workspace .


githib.com . https://github.com/settings/tokens. Weblate.


() , , sphinx-. gitUser gitToken .


#!/bin/bash
gitToken="111111111111111111111111111111111"
gitUser="user"

curDir=`pwd`
cd ${0%/*} && scriptDir=`pwd` && cd $curDir

l10nDir=$scriptDir/iondv-docs-l10n
docsDir=$l10nDir/docs-ru

if [ -d $l10nDir ]; then
  cd $l10nDir
  git branch | grep "^* translation"
  if [ $? -ne 0 ]; then git checkout translation; git branch | grep "^* translation"; if [ $? -ne 0 ]; then echo "    translation "; exit; fi
fi
  resPull=`git pull`
  resPullSatus=$?
  cd $curDir
  echo -n "  l10n: " && echo $resPull | grep "Already up to date"
  if [ $? -eq 0 ]; then echo "  l10n"; fi
else
  git clone https://$gitUser:$gitToken@github.com/iondv/docs-l10n -b translation $l10nDir
  cd $l10nDir
  git branch | grep "^* translation"
  if [ $? -ne 0 ]; then echo "    translation "; exit; fi
fi

if [ -d $docsDir/.git ]; then
  cd $docsDir
  resPull=`git pull`
  resPullSatus=$?
  cd $curDir
  echo -n "  docs-ru: " && echo $resPull | grep "Already up to date"
  if [ $? -eq 0 ]; then echo " . "; exit; fi
else
  git clone https://$gitUser:$gitToken@github.com/iondv/docs-ru $docsDir
fi

docker run -it --rm -v $l10nDir:/docs sphinx sphinx-build -b gettext /docs/docs-ru /docs/gettext
if [ $? -ne 0 ]; then echo "  gettex"; exit 1; fi
docker run -it --rm -v $l10nDir:/docs sphinx sphinx-intl update -p /docs/gettext -l en
if [ $? -ne 0 ]; then echo "  "; exit 1; fi
docker run -it --rm -v $l10nDir:/docs sphinx chmod -R ugo+r /docs/gettext /docs/locales

curDate=`date +"%Y%m%d-%H-%M"`
cd $l10nDir
gitStatus=`git status | grep "nothing to commit, working tree clean"`
if [ $? -eq 0 ]; then
  echo " "
  exit 0
else
  echo " "
  git add .
  git commit -a -m "$curDate autoupdate sphinx locales"
  git push
fi

Weblate


, . () – [] (https://weblate.iondv.com/projects/docs/) – .


– , .


– gettex. , , .



. , , .



URL – , . https://USER:123@github.com/iondv/docs-l10n, USER – , 123 .



« ». gettex – .. sphinx pot.



, . , index docs.


, , – .. . weblate://docs/index.


.



( , ). , – .. https://github.com/iondv/docs-l10n . , , «».



, translation. master. , gettex – sphinx- inondv/docs-ru. locales/en/LC_MESSAGES .



readthedocs.org


readthedocs.io .


iondv/docs-l10n. url NAME.reathedocs.io. «Edit advanced project options» — , . , – .



Build – . iondv/docs-l10n, iondv/docs-ru.


“View docs”, , translate master.


. , «iondv-ru» iondv/docs-ru. «Edit advanced project options» «Russian». , , «iondv» «Admin» «Translations» «iondv-ru»


, :



:


  • , ;
  • Weblate;
  • iondv.framework readthedocs, ;
  • , ;
  • , ;
  • .
  • weblate ( ).

. , . weblate. – ERR_MSG=' ', ERR_ MSG="Server\'s up and running.'. , GNU gettext, .


– .


– facebook LinkedIn.

More articles:


All Articles