Мой личный pandas. Как я переводила документацию

Дата публикации: 30.09.2022

Только ленивый сейчас не интересуется Data Science и анализом данных, как мне кажется. Я не ленивая, так что тоже интересуюсь. Как в 2016 году познакомилась поближе с этой областью, так с тех пор и интересуюсь. И один из любимых моих инструментов для анализа данных — это, как нетрудно догадаться, pandas. Поэтому мне не жалко было в этом году потратить три, а то и четыре месяца на перевод части официальной документации, а именно раздела Getting started. Зато теперь у меня на домашнем компьютере есть собственноручно собранная библиотека pandas с документацией на русском. Для широкой публики русскоязычная документация pandas доступна на GeekWriter.

Рассказываю, как я ее переводила.

Последовательность действий

Вкратце, последовательность действий была такова:

  1. Скомпилировала свою локальную копию pandas.

  2. Сделала копию папки с документацией и внесла в нее необходимые доработки.

  3. Сгенерировала po-файлы для перевода.

  4. Перевела po-файлы в Smartcat.

  5. Собрала переведенную документацию.

Теперь подробее о каждом шаге.

Сборка pandas

На этом этапе я руководствовалась официальной документацией pandas:

  1. Подготовила среду для сборки pandas по инструкции Creating a development environment.

  2. Подготовила виртуальную среду как описано в разделе Creating a Python environment. Для виртуальной среды использовала Миниконду.

  3. Склонировала репозиторий pandas из Github и скомпилировала pandas:

    python setup.py build_ext -j 4

  4. Сгенерировала документацию pandas как описано в разделе Building the documentation.

Скажу честно, не все шло гладко, и в конечном счете на выходе появились некоторые ошибки. Тем не менее собранный мною pandas успешно импортировался (командой import pandas) и мне удалось выполнить некоторые простые операции с наборами данных. Так что я понадеялсь, что ошибки некритичны для разработки документации (и оказалась права).

Доработка исходной документации

Исходные файлы документации — это файлы в формате RST, из которых с помощью генератора документации Sphinx на выходе получается HTML-документация. Файлы RST и прочие необходимые файлы находятся в репозитории pandas в папке doc/source.

  1. Для работы над переводом я сделала в папке doc копию папки source с именем sourceru.

  2. Из папки sourceru удалила все вложенные папки с rst-исходниками (userguide, reference, development, whatsnew) и оставила только папку getting_started и прочие папки, в которых находились файлы других форматов, необходимые для сборки документации.

  3. В некоторых RST файлах пришлось сделать небольшие доработки. Кроме того, существенно переработала файл index.rst.template (этот файл используется для генерации файла index.rst) и conf.py.

  4. В папке doc я сделала копию файла make.py под именем makeru.py и прописала в нем актуальную для меня папку с исходниками:

    SOURCE_PATH = os.path.join(DOC_PATH, "sourceru")

    Теперь этот файл можно было использовать для запуска сборки документации, а точнее, одного из ее разделов, как это описано в Building the documentation:

    python makeru.py --single getting_started/index.rst

    (Команда запускается в папке doc)

Подготовка po-файлов

  1. В виртуальную среду, подготовленную в процессе сборки pandas, я дополнительно установила sphinx-intl.

  2. В файл conf.py добавила секцию:

    # -- Options for localization -----------------------------
locale_dirs = ['locale/']
gettext_compact = False

    Также в файле conf.py указала параметр language = "ru".

  3. Сгенерировала po-файлы для перевода двумя последовательными командами:

    make gettext

    sphinx-intl update -p _build/gettext -l ru

    (Команды запускаются в папке sourceru)

Более подробно процесс перевода документации с помощью sphinx-intl описан в пошаговом руководстве.

Перевод в Smartcat

Для перевода po-файлов я использовала платформу Smartcat. Качество претранслейта мне понравилось. На бесплатном аккаунте есть ограничение на количество так называемых «smartwords» (это примерно соответствует количеству слов документации, которые вы можете перевести автоматически). Если 5000 в месяц мне хватало, то когда лимит уменьшили до 3000, стало маловато. Пришлось заводить дополнительный аккаунт.

Немного статистики о том, сколько мне потребовалось smartwords для перевода:

Файл

smartwords

index.po

783

install.po

1411

overview.po

1094

tutorials.po

394

01_table_oriented.po

609

02_read_write.po

674

03_subset_data.po

1162

04_plotting.po

461

05_add_columns.po

417

06_calculate_statistics.po

745

07_reshape_table_layout.po

972

08_combine_dataframes.po

813

09_timeseries.po

1024

10_text_data.po

772

comparison_with_r.po

1211

comparison_with_sas.po

1701

comparison_with_spreadsheets.po

2032

comparison_with_sql.po

897

comparison_with_stata.po

1718

Итого

18890

Финальная сборка документации

После того, как все файлы переведены, сборка переведенной документации запускается командой:

python makeru.py --single getting_started/index.rst

Однако это еще не все. В исходниках документации pandas не все строки строго в формате RST, а есть некоторые вкрапления HTML-разметки, вроде этой:

.. raw:: html

                                                </span>
                                        </div>
                                </div>
                        </div>
                </div>

                <div class="card tutorial-card">
                        <div class="card-header collapsed card-link" data-toggle="collapse" data-target="#collapseTen">
                                <div class="d-flex flex-row tutorial-card-header-1">
                                        <div class="d-flex flex-row tutorial-card-header-2">
                                                <button class="btn btn-dark btn-sm"></button>
                                                How to manipulate textual data?
                                        </div>
                                        <span class="badge gs-badge-link">

Тексты из такой разметки не извлекаются в po-файлы, а значит, они остаются непереведенными. В вышеприведенном примере строка «How to manipulate textual data?» так и остается в финальной документации на английском языке, а не на русском. Поэтому пришлось доработать готовую документацию: написать скрипт для замены таких строк в готовых HTML-файлах.

Вот список замен, которые пришлось выполнить:

Learn more -> Подробнее
What kind of data does pandas handle? -> Какие данные обрабатывает pandas?
How do I read and write tabular data? -> Как читать и записывать табличные данные?
How do I select a subset of a table? -> Как выбрать подмножество из DataFrame?
How to create plots in pandas? -> Как создавать диаграммы в pandas?
How to create new columns derived from existing columns? -> Как создать новые столбцы, производные от существующих?
How to calculate summary statistics? -> Как рассчитать сводную статистику?
How to reshape the layout of tables? -> Как изменять структуру таблиц?
How to combine data from multiple tables? -> Как объединить данные из нескольких таблиц?
How to handle time series data? -> Как легко обрабатывать данные временных рядов?
How to manipulate textual data? -> Как работать с текстовыми данными?
To user guide -> В руководстве пользователя
Straight to tutorial… -> Ко вводному уроку
To introduction tutorial -> Ко вводному уроку
To raw data -> Исходные данные
On this page -> На этой странице
Data used for this tutorial: -> Данные, использованные в этом уроке:
Titanic data -> Данные о Титанике
Air quality data -> Данные о качестве воздуха
Air quality Nitrate data -> Данные о качестве воздуха: концентрация двуокиси азота
Air quality Particulate matter data -> Данные о качестве воздуха: твердые частицы
REMEMBER -> ЗАПОМНИТЕ
"Search the docs ..." -> "Поиск по документации ..."

На этом, кажется, все.