Skip to content

[GH-2911] Translate Tutorial / Programming Guide (part 1) to Chinese#2931

Merged
jiayuasu merged 1 commit intoapache:masterfrom
jiayuasu:feature/docs-i18n-tutorial-part1
May 8, 2026
Merged

[GH-2911] Translate Tutorial / Programming Guide (part 1) to Chinese#2931
jiayuasu merged 1 commit intoapache:masterfrom
jiayuasu:feature/docs-i18n-tutorial-part1

Conversation

@jiayuasu
Copy link
Copy Markdown
Member

@jiayuasu jiayuasu commented May 8, 2026

Did you read the Contributor Guide?

Is this PR related to a ticket?

What changes were proposed in this PR?

Phase 4a of the Chinese-documentation EPIC (#2867). Adds Chinese (zh) translations for 17 of 27 tutorial pages so most of /zh/tutorial/ renders in Chinese on the docs site.

Translated in this PR (17 files, ~2,300 lines of translated content):

  • Top-level: viz-gallery, benchmark, jupyter-notebook, demo, storing-blobs-in-parquet, zeppelin, Advanced-Tutorial-Tune-your-Application, sql-pure-sql, viz
  • concepts/: clustering-algorithms, distance-spark
  • files/: csv-geometry-sedona-spark, geopackage-sedona-spark, shapefiles-sedona-spark, geojson-sedona-spark, geotiffmetadata-sedona-spark
  • flink/: pyflink-sql

Deferred to Phase 4b (10 large files, ~5,400 lines combined): geoparquet-sedona-spark, geopandas-shapely, geopandas-api, concepts/spatial-joins, files/stac-sedona-spark, flink/sql, snowflake/sql, raster, rdd, sql. These four files alone (sql.md 1,438 lines, rdd.md 871, raster.md 764, snowflake/sql.md 618) would dominate review of a single PR. Splitting keeps both reviews focused.

Code blocks, command snippets, version macros ({{ sedona.current_version }}, {{ sedona.current_geotools }}), admonitions, and inline tab attributes (=== "Scala", etc.) are preserved verbatim. Only prose, headings, table headers, and explanatory inline comments are translated.

How was this patch tested?

Built the docs locally with uv sync --group docs && uv run mkdocs build and verified:

  • The build succeeds with no new warnings introduced by Phase 4a.
  • 17 new *.zh.md files are picked up by mkdocs-static-i18n and rendered under /zh/tutorial/, /zh/tutorial/concepts/, /zh/tutorial/files/, /zh/tutorial/flink/.
  • Untranslated pages (the 10 deferred to Phase 4b) still fall back to English content via fallback_to_default: true, so /zh/tutorial/ is fully navigable today.
  • pre-commit run --all-files passes including the blacken-docs hook (one-time fixup: split a code block in distance-spark.zh.md that mixed Python and Spark .show() ASCII output, which blacken-docs rejects when it tries to parse the table separators as Python).

Some [link](../page.md#english-anchor) references continue to produce INFO log lines about missing anchors in the new zh files. The pages still resolve; only the in-page jump is lost. Establishing stable explicit anchors (## Title { #stable-anchor }) is a separate cross-cutting concern best handled across all phases at once.

Did this PR include necessary documentation updates?

  • Yes, this PR is itself a documentation translation. Phase 4b will translate the remaining 10 tutorial pages.

…inese

Phase 4a of apache#2867. Adds Chinese translations for 17 of 27 tutorial
pages. The remaining 10 large pages (geoparquet, geopandas-shapely,
geopandas-api, spatial-joins, stac, flink/sql, snowflake/sql, raster,
rdd, sql) are deferred to a follow-up PR (Phase 4b) to keep this one
review-able — together they are ~5,400 lines and warrant their own
review pass.

Files translated in this PR:
- Top-level: viz-gallery, benchmark, jupyter-notebook, demo,
  storing-blobs-in-parquet, zeppelin,
  Advanced-Tutorial-Tune-your-Application, sql-pure-sql, viz
- concepts/: clustering-algorithms, distance-spark
- files/: csv-geometry, geopackage, shapefiles, geojson, geotiffmetadata
- flink/: pyflink-sql

Code blocks, command snippets, version macros, admonitions, and
inline tab attributes (=== "Scala", etc.) are preserved verbatim.
Only prose, headings, table headers, and explanatory inline comments
are translated.

A handful of `[link](../page.md#english-anchor)` references resolve
the page but lose the anchor jump because the translated headings
auto-generate Chinese anchors. Establishing stable explicit anchors
across all phases is a separate cross-cutting cleanup.
@jiayuasu jiayuasu linked an issue May 8, 2026 that may be closed by this pull request
@jiayuasu jiayuasu merged commit b3bdd1d into apache:master May 8, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[GH-2867] Translate Tutorial / Programming Guide to Chinese (Phase 4)

1 participant