Sebastián Ramírez
6 months ago
committed by
GitHub
GitHub
102 changed files with 9917 additions and 2005 deletions
@ -15,6 +15,7 @@ jobs: |
|||
- fastapi-slim |
|||
permissions: |
|||
id-token: write |
|||
contents: read |
|||
steps: |
|||
- name: Dump GitHub context |
|||
env: |
|||
@ -24,19 +25,15 @@ jobs: |
|||
- name: Set up Python |
|||
uses: actions/setup-python@v6 |
|||
with: |
|||
python-version: "3.10" |
|||
python-version-file: ".python-version" |
|||
# Issue ref: https://github.com/actions/setup-python/issues/436 |
|||
# cache: "pip" |
|||
# cache-dependency-path: pyproject.toml |
|||
- name: Install build dependencies |
|||
run: pip install build |
|||
- name: Install uv |
|||
uses: astral-sh/setup-uv@v7 |
|||
- name: Build distribution |
|||
run: uv build |
|||
env: |
|||
TIANGOLO_BUILD_PACKAGE: ${{ matrix.package }} |
|||
run: python -m build |
|||
- name: Publish |
|||
uses: pypa/[email protected] |
|||
- name: Dump GitHub context |
|||
env: |
|||
GITHUB_CONTEXT: ${{ toJson(github) }} |
|||
run: echo "$GITHUB_CONTEXT" |
|||
run: uv publish |
|||
|
|||
@ -0,0 +1 @@ |
|||
3.11 |
|||
@ -46,12 +46,6 @@ $ pip install "fastapi[all]" |
|||
|
|||
</div> |
|||
|
|||
/// info | Información |
|||
|
|||
En Pydantic v1 venía incluido con el paquete principal. Ahora se distribuye como este paquete independiente para que puedas elegir si instalarlo o no si no necesitas esa funcionalidad. |
|||
|
|||
/// |
|||
|
|||
### Crear el objeto `Settings` { #create-the-settings-object } |
|||
|
|||
Importa `BaseSettings` de Pydantic y crea una sub-clase, muy similar a un modelo de Pydantic. |
|||
@ -60,31 +54,15 @@ De la misma forma que con los modelos de Pydantic, declaras atributos de clase c |
|||
|
|||
Puedes usar todas las mismas funcionalidades de validación y herramientas que usas para los modelos de Pydantic, como diferentes tipos de datos y validaciones adicionales con `Field()`. |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
/// info | Información |
|||
|
|||
En Pydantic v1 importarías `BaseSettings` directamente desde `pydantic` en lugar de desde `pydantic_settings`. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/settings/tutorial001_pv1_py39.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
/// tip | Consejo |
|||
|
|||
Si quieres algo rápido para copiar y pegar, no uses este ejemplo, usa el último más abajo. |
|||
|
|||
/// |
|||
|
|||
Luego, cuando creas una instance de esa clase `Settings` (en este caso, en el objeto `settings`), Pydantic leerá las variables de entorno de una manera indiferente a mayúsculas y minúsculas, por lo que una variable en mayúsculas `APP_NAME` aún será leída para el atributo `app_name`. |
|||
Luego, cuando creas un instance de esa clase `Settings` (en este caso, en el objeto `settings`), Pydantic leerá las variables de entorno de una manera indiferente a mayúsculas y minúsculas, por lo que una variable en mayúsculas `APP_NAME` aún será leída para el atributo `app_name`. |
|||
|
|||
Luego convertirá y validará los datos. Así que, cuando uses ese objeto `settings`, tendrás datos de los tipos que declaraste (por ejemplo, `items_per_user` será un `int`). |
|||
|
|||
@ -110,7 +88,7 @@ $ ADMIN_EMAIL="[email protected]" APP_NAME="ChimichangApp" fastapi run main.p |
|||
|
|||
/// tip | Consejo |
|||
|
|||
Para establecer múltiples variables de entorno para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando. |
|||
Para establecer múltiples env vars para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando. |
|||
|
|||
/// |
|||
|
|||
@ -150,7 +128,7 @@ Proveniente del ejemplo anterior, tu archivo `config.py` podría verse como: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/config.py hl[10] *} |
|||
|
|||
Nota que ahora no creamos una instance por defecto `settings = Settings()`. |
|||
Nota que ahora no creamos un instance por defecto `settings = Settings()`. |
|||
|
|||
### El archivo principal de la app { #the-main-app-file } |
|||
|
|||
@ -172,11 +150,11 @@ Y luego podemos requerirlo desde la *path operation function* como una dependenc |
|||
|
|||
### Configuraciones y pruebas { #settings-and-testing } |
|||
|
|||
Luego sería muy fácil proporcionar un objeto de configuraciones diferente durante las pruebas al sobrescribir una dependencia para `get_settings`: |
|||
Luego sería muy fácil proporcionar un objeto de configuraciones diferente durante las pruebas al crear una sobrescritura de dependencia para `get_settings`: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/test_main.py hl[9:10,13,21] *} |
|||
|
|||
En la dependencia sobreescrita establecemos un nuevo valor para el `admin_email` al crear el nuevo objeto `Settings`, y luego devolvemos ese nuevo objeto. |
|||
En la sobrescritura de dependencia establecemos un nuevo valor para el `admin_email` al crear el nuevo objeto `Settings`, y luego devolvemos ese nuevo objeto. |
|||
|
|||
Luego podemos probar que se está usando. |
|||
|
|||
@ -215,8 +193,6 @@ APP_NAME="ChimichangApp" |
|||
|
|||
Y luego actualizar tu `config.py` con: |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} |
|||
|
|||
/// tip | Consejo |
|||
@ -225,26 +201,6 @@ El atributo `model_config` se usa solo para configuración de Pydantic. Puedes l |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/config_pv1.py hl[9:10] *} |
|||
|
|||
/// tip | Consejo |
|||
|
|||
La clase `Config` se usa solo para configuración de Pydantic. Puedes leer más en <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
/// info | Información |
|||
|
|||
En la versión 1 de Pydantic la configuración se hacía en una clase interna `Config`, en la versión 2 de Pydantic se hace en un atributo `model_config`. Este atributo toma un `dict`, y para obtener autocompletado y errores en línea, puedes importar y usar `SettingsConfigDict` para definir ese `dict`. |
|||
|
|||
/// |
|||
|
|||
Aquí definimos la configuración `env_file` dentro de tu clase Pydantic `Settings`, y establecemos el valor en el nombre del archivo con el archivo dotenv que queremos usar. |
|||
|
|||
### Creando el `Settings` solo una vez con `lru_cache` { #creating-the-settings-only-once-with-lru-cache } |
|||
@ -331,7 +287,7 @@ participant execute as Ejecutar función |
|||
end |
|||
``` |
|||
|
|||
En el caso de nuestra dependencia `get_settings()`, la función ni siquiera toma argumentos, por lo que siempre devolverá el mismo valor. |
|||
En el caso de nuestra dependencia `get_settings()`, la función ni siquiera toma argumentos, por lo que siempre devuelve el mismo valor. |
|||
|
|||
De esa manera, se comporta casi como si fuera solo una variable global. Pero como usa una función de dependencia, entonces podemos sobrescribirla fácilmente para las pruebas. |
|||
|
|||
|
|||
@ -22,21 +22,13 @@ Aquí tienes una idea general de cómo podrían ser los modelos con sus campos d |
|||
|
|||
{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} |
|||
|
|||
/// info | Información |
|||
### Acerca de `**user_in.model_dump()` { #about-user-in-model-dump } |
|||
|
|||
En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`. |
|||
|
|||
Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2. |
|||
|
|||
/// |
|||
|
|||
### Acerca de `**user_in.dict()` { #about-user-in-dict } |
|||
|
|||
#### `.dict()` de Pydantic { #pydantics-dict } |
|||
#### `.model_dump()` de Pydantic { #pydantics-model-dump } |
|||
|
|||
`user_in` es un modelo Pydantic de la clase `UserIn`. |
|||
|
|||
Los modelos Pydantic tienen un método `.dict()` que devuelve un `dict` con los datos del modelo. |
|||
Los modelos Pydantic tienen un método `.model_dump()` que devuelve un `dict` con los datos del modelo. |
|||
|
|||
Así que, si creamos un objeto Pydantic `user_in` como: |
|||
|
|||
@ -47,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="[email protected] |
|||
y luego llamamos a: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
``` |
|||
|
|||
ahora tenemos un `dict` con los datos en la variable `user_dict` (es un `dict` en lugar de un objeto modelo Pydantic). |
|||
@ -58,7 +50,7 @@ Y si llamamos a: |
|||
print(user_dict) |
|||
``` |
|||
|
|||
obtendremos un `dict` de Python con: |
|||
obtendríamos un `dict` de Python con: |
|||
|
|||
```Python |
|||
{ |
|||
@ -103,20 +95,20 @@ UserInDB( |
|||
|
|||
#### Un modelo Pydantic a partir del contenido de otro { #a-pydantic-model-from-the-contents-of-another } |
|||
|
|||
Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.dict()`, este código: |
|||
Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.model_dump()`, este código: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
UserInDB(**user_dict) |
|||
``` |
|||
|
|||
sería equivalente a: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict()) |
|||
UserInDB(**user_in.model_dump()) |
|||
``` |
|||
|
|||
...porque `user_in.dict()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`. |
|||
...porque `user_in.model_dump()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`. |
|||
|
|||
Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic. |
|||
|
|||
@ -125,7 +117,7 @@ Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic |
|||
Y luego agregando el argumento de palabra clave adicional `hashed_password=hashed_password`, como en: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict(), hashed_password=hashed_password) |
|||
UserInDB(**user_in.model_dump(), hashed_password=hashed_password) |
|||
``` |
|||
|
|||
...termina siendo como: |
|||
@ -156,7 +148,7 @@ Y estos modelos están compartiendo muchos de los datos y duplicando nombres y t |
|||
|
|||
Podríamos hacerlo mejor. |
|||
|
|||
Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (anotaciones de tipos, validación, etc). |
|||
Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (declaraciones de tipos, validación, etc). |
|||
|
|||
Toda la conversión de datos, validación, documentación, etc. seguirá funcionando normalmente. |
|||
|
|||
@ -180,20 +172,19 @@ Al definir una <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" |
|||
|
|||
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *} |
|||
|
|||
|
|||
### `Union` en Python 3.10 { #union-in-python-3-10 } |
|||
|
|||
En este ejemplo pasamos `Union[PlaneItem, CarItem]` como el valor del argumento `response_model`. |
|||
|
|||
Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en **anotaciones de tipos**, tenemos que usar `Union` incluso en Python 3.10. |
|||
Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en una **anotación de tipos**, tenemos que usar `Union` incluso en Python 3.10. |
|||
|
|||
Si estuviera en anotaciones de tipos podríamos haber usado la barra vertical, como: |
|||
Si estuviera en una anotación de tipos podríamos haber usado la barra vertical, como: |
|||
|
|||
```Python |
|||
some_variable: PlaneItem | CarItem |
|||
``` |
|||
|
|||
Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como anotaciones de tipos. |
|||
Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como una anotación de tipos. |
|||
|
|||
## Lista de modelos { #list-of-models } |
|||
|
|||
@ -203,7 +194,6 @@ Para eso, usa el `typing.List` estándar de Python (o simplemente `list` en Pyth |
|||
|
|||
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} |
|||
|
|||
|
|||
## Response con `dict` arbitrario { #response-with-arbitrary-dict } |
|||
|
|||
También puedes declarar un response usando un `dict` arbitrario plano, declarando solo el tipo de las claves y valores, sin usar un modelo Pydantic. |
|||
@ -214,7 +204,6 @@ En este caso, puedes usar `typing.Dict` (o solo `dict` en Python 3.9 y posterior |
|||
|
|||
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *} |
|||
|
|||
|
|||
## Recapitulación { #recap } |
|||
|
|||
Usa múltiples modelos Pydantic y hereda libremente para cada caso. |
|||
|
|||
@ -1,4 +0,0 @@ |
|||
# For mkdocstrings and tests |
|||
httpx >=0.23.0,<1.0.0 |
|||
# For linting and generating docs versions |
|||
ruff ==0.14.3 |
|||
@ -1,21 +0,0 @@ |
|||
-e . |
|||
-r requirements-docs-tests.txt |
|||
mkdocs-material==9.7.0 |
|||
mdx-include >=1.4.1,<2.0.0 |
|||
mkdocs-redirects>=1.2.1,<1.3.0 |
|||
typer == 0.16.0 |
|||
pyyaml >=5.3.1,<7.0.0 |
|||
# For Material for MkDocs, Chinese search |
|||
jieba==0.42.1 |
|||
# For image processing by Material for MkDocs |
|||
pillow==11.3.0 |
|||
# For image processing by Material for MkDocs |
|||
cairosvg==2.8.2 |
|||
mkdocstrings[python]==0.30.1 |
|||
griffe-typingdoc==0.3.0 |
|||
griffe-warnings-deprecated==1.1.0 |
|||
# For griffe, it formats with black |
|||
black==25.1.0 |
|||
mkdocs-macros-plugin==1.4.1 |
|||
markdown-include-variants==0.0.8 |
|||
python-slugify==8.0.4 |
|||
@ -1,6 +0,0 @@ |
|||
PyGithub>=2.3.0,<3.0.0 |
|||
pydantic>=2.5.3,<3.0.0 |
|||
pydantic-settings>=2.1.0,<3.0.0 |
|||
httpx>=0.27.0,<1.0.0 |
|||
pyyaml >=5.3.1,<7.0.0 |
|||
smokeshow |
|||
@ -1,18 +0,0 @@ |
|||
-e .[all] |
|||
-r requirements-docs-tests.txt |
|||
pytest >=7.1.3,<9.0.0 |
|||
coverage[toml] >= 6.5.0,< 8.0 |
|||
mypy ==1.14.1 |
|||
dirty-equals ==0.9.0 |
|||
sqlmodel==0.0.27 |
|||
flask >=1.1.2,<4.0.0 |
|||
strawberry-graphql >=0.200.0,< 1.0.0 |
|||
anyio[trio] >=3.2.1,<5.0.0 |
|||
PyJWT==2.9.0 |
|||
pyyaml >=5.3.1,<7.0.0 |
|||
pwdlib[argon2] >=0.2.1 |
|||
inline-snapshot>=0.21.1 |
|||
pytest-codspeed==4.2.0 |
|||
# types |
|||
types-ujson ==5.10.0.20240515 |
|||
types-orjson ==3.6.2 |
|||
@ -1,3 +0,0 @@ |
|||
pydantic-ai==0.4.10 |
|||
GitPython==3.1.45 |
|||
pygithub==2.8.1 |
|||
@ -1,7 +0,0 @@ |
|||
-e .[all] |
|||
-r requirements-tests.txt |
|||
-r requirements-docs.txt |
|||
-r requirements-translations.txt |
|||
prek==0.2.22 |
|||
# For generating screenshots |
|||
playwright |
|||
@ -0,0 +1,733 @@ |
|||
import re |
|||
from typing import TypedDict, Union |
|||
|
|||
CODE_INCLUDE_RE = re.compile(r"^\{\*\s*(\S+)\s*(.*)\*\}$") |
|||
CODE_INCLUDE_PLACEHOLDER = "<CODE_INCLUDE>" |
|||
|
|||
HEADER_WITH_PERMALINK_RE = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})?\s*$") |
|||
HEADER_LINE_RE = re.compile(r"^(#{1,6}) (.+?)(?:\s*\{\s*(#.*)\s*\})?\s*$") |
|||
|
|||
TIANGOLO_COM = "https://fastapi.tiangolo.com" |
|||
ASSETS_URL_PREFIXES = ("/img/", "/css/", "/js/") |
|||
|
|||
MARKDOWN_LINK_RE = re.compile( |
|||
r"(?<!\\)(?<!\!)" # not an image ![...] and not escaped \[...] |
|||
r"\[(?P<text>.*?)\]" # link text (non-greedy) |
|||
r"\(" |
|||
r"(?P<url>[^)\s]+)" # url (no spaces and `)`) |
|||
r'(?:\s+["\'](?P<title>.*?)["\'])?' # optional title in "" or '' |
|||
r"\)" |
|||
r"(?:\s*\{(?P<attrs>[^}]*)\})?" # optional attributes in {} |
|||
) |
|||
|
|||
HTML_LINK_RE = re.compile(r"<a\s+[^>]*>.*?</a>") |
|||
HTML_LINK_TEXT_RE = re.compile(r"<a\b([^>]*)>(.*?)</a>") |
|||
HTML_LINK_OPEN_TAG_RE = re.compile(r"<a\b([^>]*)>") |
|||
HTML_ATTR_RE = re.compile(r'(\w+)\s*=\s*([\'"])(.*?)\2') |
|||
|
|||
CODE_BLOCK_LANG_RE = re.compile(r"^`{3,4}([\w-]*)", re.MULTILINE) |
|||
|
|||
SLASHES_COMMENT_RE = re.compile( |
|||
r"^(?P<code>.*?)(?P<comment>(?:(?<= )// .*)|(?:^// .*))?$" |
|||
) |
|||
|
|||
HASH_COMMENT_RE = re.compile(r"^(?P<code>.*?)(?P<comment>(?:(?<= )# .*)|(?:^# .*))?$") |
|||
|
|||
|
|||
class CodeIncludeInfo(TypedDict): |
|||
line_no: int |
|||
line: str |
|||
|
|||
|
|||
class HeaderPermalinkInfo(TypedDict): |
|||
line_no: int |
|||
hashes: str |
|||
title: str |
|||
permalink: str |
|||
|
|||
|
|||
class MarkdownLinkInfo(TypedDict): |
|||
line_no: int |
|||
url: str |
|||
text: str |
|||
title: Union[str, None] |
|||
attributes: Union[str, None] |
|||
full_match: str |
|||
|
|||
|
|||
class HTMLLinkAttribute(TypedDict): |
|||
name: str |
|||
quote: str |
|||
value: str |
|||
|
|||
|
|||
class HtmlLinkInfo(TypedDict): |
|||
line_no: int |
|||
full_tag: str |
|||
attributes: list[HTMLLinkAttribute] |
|||
text: str |
|||
|
|||
|
|||
class MultilineCodeBlockInfo(TypedDict): |
|||
lang: str |
|||
start_line_no: int |
|||
content: list[str] |
|||
|
|||
|
|||
# Code includes |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def extract_code_includes(lines: list[str]) -> list[CodeIncludeInfo]: |
|||
""" |
|||
Extract lines that contain code includes. |
|||
|
|||
Return list of CodeIncludeInfo, where each dict contains: |
|||
- `line_no` - line number (1-based) |
|||
- `line` - text of the line |
|||
""" |
|||
|
|||
includes: list[CodeIncludeInfo] = [] |
|||
for line_no, line in enumerate(lines, start=1): |
|||
if CODE_INCLUDE_RE.match(line): |
|||
includes.append(CodeIncludeInfo(line_no=line_no, line=line)) |
|||
return includes |
|||
|
|||
|
|||
def replace_code_includes_with_placeholders(text: list[str]) -> list[str]: |
|||
""" |
|||
Replace code includes with placeholders. |
|||
""" |
|||
|
|||
modified_text = text.copy() |
|||
includes = extract_code_includes(text) |
|||
for include in includes: |
|||
modified_text[include["line_no"] - 1] = CODE_INCLUDE_PLACEHOLDER |
|||
return modified_text |
|||
|
|||
|
|||
def replace_placeholders_with_code_includes( |
|||
text: list[str], original_includes: list[CodeIncludeInfo] |
|||
) -> list[str]: |
|||
""" |
|||
Replace code includes placeholders with actual code includes from the original (English) document. |
|||
Fail if the number of placeholders does not match the number of original includes. |
|||
""" |
|||
|
|||
code_include_lines = [ |
|||
line_no |
|||
for line_no, line in enumerate(text) |
|||
if line.strip() == CODE_INCLUDE_PLACEHOLDER |
|||
] |
|||
|
|||
if len(code_include_lines) != len(original_includes): |
|||
raise ValueError( |
|||
"Number of code include placeholders does not match the number of code includes " |
|||
"in the original document " |
|||
f"({len(code_include_lines)} vs {len(original_includes)})" |
|||
) |
|||
|
|||
modified_text = text.copy() |
|||
for i, line_no in enumerate(code_include_lines): |
|||
modified_text[line_no] = original_includes[i]["line"] |
|||
|
|||
return modified_text |
|||
|
|||
|
|||
# Header permalinks |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def extract_header_permalinks(lines: list[str]) -> list[HeaderPermalinkInfo]: |
|||
""" |
|||
Extract list of header permalinks from the given lines. |
|||
|
|||
Return list of HeaderPermalinkInfo, where each dict contains: |
|||
- `line_no` - line number (1-based) |
|||
- `hashes` - string of hashes representing header level (e.g., "###") |
|||
- `permalink` - permalink string (e.g., "{#permalink}") |
|||
""" |
|||
|
|||
headers: list[HeaderPermalinkInfo] = [] |
|||
in_code_block3 = False |
|||
in_code_block4 = False |
|||
|
|||
for line_no, line in enumerate(lines, start=1): |
|||
if not (in_code_block3 or in_code_block4): |
|||
if line.startswith("```"): |
|||
count = len(line) - len(line.lstrip("`")) |
|||
if count == 3: |
|||
in_code_block3 = True |
|||
continue |
|||
elif count >= 4: |
|||
in_code_block4 = True |
|||
continue |
|||
|
|||
header_match = HEADER_WITH_PERMALINK_RE.match(line) |
|||
if header_match: |
|||
hashes, title, permalink = header_match.groups() |
|||
headers.append( |
|||
HeaderPermalinkInfo( |
|||
hashes=hashes, line_no=line_no, permalink=permalink, title=title |
|||
) |
|||
) |
|||
|
|||
elif in_code_block3: |
|||
if line.startswith("```"): |
|||
count = len(line) - len(line.lstrip("`")) |
|||
if count == 3: |
|||
in_code_block3 = False |
|||
continue |
|||
|
|||
elif in_code_block4: |
|||
if line.startswith("````"): |
|||
count = len(line) - len(line.lstrip("`")) |
|||
if count >= 4: |
|||
in_code_block4 = False |
|||
continue |
|||
|
|||
return headers |
|||
|
|||
|
|||
def remove_header_permalinks(lines: list[str]) -> list[str]: |
|||
""" |
|||
Remove permalinks from headers in the given lines. |
|||
""" |
|||
|
|||
modified_lines: list[str] = [] |
|||
for line in lines: |
|||
header_match = HEADER_WITH_PERMALINK_RE.match(line) |
|||
if header_match: |
|||
hashes, title, _permalink = header_match.groups() |
|||
modified_line = f"{hashes} {title}" |
|||
modified_lines.append(modified_line) |
|||
else: |
|||
modified_lines.append(line) |
|||
return modified_lines |
|||
|
|||
|
|||
def replace_header_permalinks( |
|||
text: list[str], |
|||
header_permalinks: list[HeaderPermalinkInfo], |
|||
original_header_permalinks: list[HeaderPermalinkInfo], |
|||
) -> list[str]: |
|||
""" |
|||
Replace permalinks in the given text with the permalinks from the original document. |
|||
|
|||
Fail if the number or level of headers does not match the original. |
|||
""" |
|||
|
|||
modified_text: list[str] = text.copy() |
|||
|
|||
if len(header_permalinks) != len(original_header_permalinks): |
|||
raise ValueError( |
|||
"Number of headers with permalinks does not match the number in the " |
|||
"original document " |
|||
f"({len(header_permalinks)} vs {len(original_header_permalinks)})" |
|||
) |
|||
|
|||
for header_no in range(len(header_permalinks)): |
|||
header_info = header_permalinks[header_no] |
|||
original_header_info = original_header_permalinks[header_no] |
|||
|
|||
if header_info["hashes"] != original_header_info["hashes"]: |
|||
raise ValueError( |
|||
"Header levels do not match between document and original document" |
|||
f" (found {header_info['hashes']}, expected {original_header_info['hashes']})" |
|||
f" for header №{header_no + 1} in line {header_info['line_no']}" |
|||
) |
|||
line_no = header_info["line_no"] - 1 |
|||
hashes = header_info["hashes"] |
|||
title = header_info["title"] |
|||
permalink = original_header_info["permalink"] |
|||
modified_text[line_no] = f"{hashes} {title}{permalink}" |
|||
|
|||
return modified_text |
|||
|
|||
|
|||
# Markdown links |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def extract_markdown_links(lines: list[str]) -> list[MarkdownLinkInfo]: |
|||
""" |
|||
Extract all markdown links from the given lines. |
|||
|
|||
Return list of MarkdownLinkInfo, where each dict contains: |
|||
- `line_no` - line number (1-based) |
|||
- `url` - link URL |
|||
- `text` - link text |
|||
- `title` - link title (if any) |
|||
""" |
|||
|
|||
links: list[MarkdownLinkInfo] = [] |
|||
for line_no, line in enumerate(lines, start=1): |
|||
for m in MARKDOWN_LINK_RE.finditer(line): |
|||
links.append( |
|||
MarkdownLinkInfo( |
|||
line_no=line_no, |
|||
url=m.group("url"), |
|||
text=m.group("text"), |
|||
title=m.group("title"), |
|||
attributes=m.group("attrs"), |
|||
full_match=m.group(0), |
|||
) |
|||
) |
|||
return links |
|||
|
|||
|
|||
def _add_lang_code_to_url(url: str, lang_code: str) -> str: |
|||
if url.startswith(TIANGOLO_COM): |
|||
rel_url = url[len(TIANGOLO_COM) :] |
|||
if not rel_url.startswith(ASSETS_URL_PREFIXES): |
|||
url = url.replace(TIANGOLO_COM, f"{TIANGOLO_COM}/{lang_code}") |
|||
return url |
|||
|
|||
|
|||
def _construct_markdown_link( |
|||
url: str, |
|||
text: str, |
|||
title: Union[str, None], |
|||
attributes: Union[str, None], |
|||
lang_code: str, |
|||
) -> str: |
|||
""" |
|||
Construct a markdown link, adjusting the URL for the given language code if needed. |
|||
""" |
|||
url = _add_lang_code_to_url(url, lang_code) |
|||
|
|||
if title: |
|||
link = f'[{text}]({url} "{title}")' |
|||
else: |
|||
link = f"[{text}]({url})" |
|||
|
|||
if attributes: |
|||
link += f"{{{attributes}}}" |
|||
|
|||
return link |
|||
|
|||
|
|||
def replace_markdown_links( |
|||
text: list[str], |
|||
links: list[MarkdownLinkInfo], |
|||
original_links: list[MarkdownLinkInfo], |
|||
lang_code: str, |
|||
) -> list[str]: |
|||
""" |
|||
Replace markdown links in the given text with the original links. |
|||
|
|||
Fail if the number of links does not match the original. |
|||
""" |
|||
|
|||
if len(links) != len(original_links): |
|||
raise ValueError( |
|||
"Number of markdown links does not match the number in the " |
|||
"original document " |
|||
f"({len(links)} vs {len(original_links)})" |
|||
) |
|||
|
|||
modified_text = text.copy() |
|||
for i, link_info in enumerate(links): |
|||
link_text = link_info["text"] |
|||
link_title = link_info["title"] |
|||
original_link_info = original_links[i] |
|||
|
|||
# Replace |
|||
replacement_link = _construct_markdown_link( |
|||
url=original_link_info["url"], |
|||
text=link_text, |
|||
title=link_title, |
|||
attributes=original_link_info["attributes"], |
|||
lang_code=lang_code, |
|||
) |
|||
line_no = link_info["line_no"] - 1 |
|||
modified_line = modified_text[line_no] |
|||
modified_line = modified_line.replace( |
|||
link_info["full_match"], replacement_link, 1 |
|||
) |
|||
modified_text[line_no] = modified_line |
|||
|
|||
return modified_text |
|||
|
|||
|
|||
# HTML links |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def extract_html_links(lines: list[str]) -> list[HtmlLinkInfo]: |
|||
""" |
|||
Extract all HTML links from the given lines. |
|||
|
|||
Return list of HtmlLinkInfo, where each dict contains: |
|||
- `line_no` - line number (1-based) |
|||
- `full_tag` - full HTML link tag |
|||
- `attributes` - list of HTMLLinkAttribute (name, quote, value) |
|||
- `text` - link text |
|||
""" |
|||
|
|||
links = [] |
|||
for line_no, line in enumerate(lines, start=1): |
|||
for html_link in HTML_LINK_RE.finditer(line): |
|||
link_str = html_link.group(0) |
|||
|
|||
link_text_match = HTML_LINK_TEXT_RE.match(link_str) |
|||
assert link_text_match is not None |
|||
link_text = link_text_match.group(2) |
|||
assert isinstance(link_text, str) |
|||
|
|||
link_open_tag_match = HTML_LINK_OPEN_TAG_RE.match(link_str) |
|||
assert link_open_tag_match is not None |
|||
link_open_tag = link_open_tag_match.group(1) |
|||
assert isinstance(link_open_tag, str) |
|||
|
|||
attributes: list[HTMLLinkAttribute] = [] |
|||
for attr_name, attr_quote, attr_value in re.findall( |
|||
HTML_ATTR_RE, link_open_tag |
|||
): |
|||
assert isinstance(attr_name, str) |
|||
assert isinstance(attr_quote, str) |
|||
assert isinstance(attr_value, str) |
|||
attributes.append( |
|||
HTMLLinkAttribute( |
|||
name=attr_name, quote=attr_quote, value=attr_value |
|||
) |
|||
) |
|||
links.append( |
|||
HtmlLinkInfo( |
|||
line_no=line_no, |
|||
full_tag=link_str, |
|||
attributes=attributes, |
|||
text=link_text, |
|||
) |
|||
) |
|||
return links |
|||
|
|||
|
|||
def _construct_html_link( |
|||
link_text: str, |
|||
attributes: list[HTMLLinkAttribute], |
|||
lang_code: str, |
|||
) -> str: |
|||
""" |
|||
Reconstruct HTML link, adjusting the URL for the given language code if needed. |
|||
""" |
|||
|
|||
attributes_upd: list[HTMLLinkAttribute] = [] |
|||
for attribute in attributes: |
|||
if attribute["name"] == "href": |
|||
original_url = attribute["value"] |
|||
url = _add_lang_code_to_url(original_url, lang_code) |
|||
attributes_upd.append( |
|||
HTMLLinkAttribute(name="href", quote=attribute["quote"], value=url) |
|||
) |
|||
else: |
|||
attributes_upd.append(attribute) |
|||
|
|||
attrs_str = " ".join( |
|||
f"{attribute['name']}={attribute['quote']}{attribute['value']}{attribute['quote']}" |
|||
for attribute in attributes_upd |
|||
) |
|||
return f"<a {attrs_str}>{link_text}</a>" |
|||
|
|||
|
|||
def replace_html_links( |
|||
text: list[str], |
|||
links: list[HtmlLinkInfo], |
|||
original_links: list[HtmlLinkInfo], |
|||
lang_code: str, |
|||
) -> list[str]: |
|||
""" |
|||
Replace HTML links in the given text with the links from the original document. |
|||
|
|||
Adjust URLs for the given language code. |
|||
Fail if the number of links does not match the original. |
|||
""" |
|||
|
|||
if len(links) != len(original_links): |
|||
raise ValueError( |
|||
"Number of HTML links does not match the number in the " |
|||
"original document " |
|||
f"({len(links)} vs {len(original_links)})" |
|||
) |
|||
|
|||
modified_text = text.copy() |
|||
for link_index, link in enumerate(links): |
|||
original_link_info = original_links[link_index] |
|||
|
|||
# Replace in the document text |
|||
replacement_link = _construct_html_link( |
|||
link_text=link["text"], |
|||
attributes=original_link_info["attributes"], |
|||
lang_code=lang_code, |
|||
) |
|||
line_no = link["line_no"] - 1 |
|||
modified_text[line_no] = modified_text[line_no].replace( |
|||
link["full_tag"], replacement_link, 1 |
|||
) |
|||
|
|||
return modified_text |
|||
|
|||
|
|||
# Multiline code blocks |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def get_code_block_lang(line: str) -> str: |
|||
match = CODE_BLOCK_LANG_RE.match(line) |
|||
if match: |
|||
return match.group(1) |
|||
return "" |
|||
|
|||
|
|||
def extract_multiline_code_blocks(text: list[str]) -> list[MultilineCodeBlockInfo]: |
|||
blocks: list[MultilineCodeBlockInfo] = [] |
|||
|
|||
in_code_block3 = False |
|||
in_code_block4 = False |
|||
current_block_lang = "" |
|||
current_block_start_line = -1 |
|||
current_block_lines = [] |
|||
|
|||
for line_no, line in enumerate(text, start=1): |
|||
stripped = line.lstrip() |
|||
|
|||
# --- Detect opening fence --- |
|||
if not (in_code_block3 or in_code_block4): |
|||
if stripped.startswith("```"): |
|||
current_block_start_line = line_no |
|||
count = len(stripped) - len(stripped.lstrip("`")) |
|||
if count == 3: |
|||
in_code_block3 = True |
|||
current_block_lang = get_code_block_lang(stripped) |
|||
current_block_lines = [line] |
|||
continue |
|||
elif count >= 4: |
|||
in_code_block4 = True |
|||
current_block_lang = get_code_block_lang(stripped) |
|||
current_block_lines = [line] |
|||
continue |
|||
|
|||
# --- Detect closing fence --- |
|||
elif in_code_block3: |
|||
if stripped.startswith("```"): |
|||
count = len(stripped) - len(stripped.lstrip("`")) |
|||
if count == 3: |
|||
current_block_lines.append(line) |
|||
blocks.append( |
|||
MultilineCodeBlockInfo( |
|||
lang=current_block_lang, |
|||
start_line_no=current_block_start_line, |
|||
content=current_block_lines, |
|||
) |
|||
) |
|||
in_code_block3 = False |
|||
current_block_lang = "" |
|||
current_block_start_line = -1 |
|||
current_block_lines = [] |
|||
continue |
|||
current_block_lines.append(line) |
|||
|
|||
elif in_code_block4: |
|||
if stripped.startswith("````"): |
|||
count = len(stripped) - len(stripped.lstrip("`")) |
|||
if count >= 4: |
|||
current_block_lines.append(line) |
|||
blocks.append( |
|||
MultilineCodeBlockInfo( |
|||
lang=current_block_lang, |
|||
start_line_no=current_block_start_line, |
|||
content=current_block_lines, |
|||
) |
|||
) |
|||
in_code_block4 = False |
|||
current_block_lang = "" |
|||
current_block_start_line = -1 |
|||
current_block_lines = [] |
|||
continue |
|||
current_block_lines.append(line) |
|||
|
|||
return blocks |
|||
|
|||
|
|||
def _split_hash_comment(line: str) -> tuple[str, Union[str, None]]: |
|||
match = HASH_COMMENT_RE.match(line) |
|||
if match: |
|||
code = match.group("code").rstrip() |
|||
comment = match.group("comment") |
|||
return code, comment |
|||
return line.rstrip(), None |
|||
|
|||
|
|||
def _split_slashes_comment(line: str) -> tuple[str, Union[str, None]]: |
|||
match = SLASHES_COMMENT_RE.match(line) |
|||
if match: |
|||
code = match.group("code").rstrip() |
|||
comment = match.group("comment") |
|||
return code, comment |
|||
return line, None |
|||
|
|||
|
|||
def replace_multiline_code_block( |
|||
block_a: MultilineCodeBlockInfo, block_b: MultilineCodeBlockInfo |
|||
) -> list[str]: |
|||
""" |
|||
Replace multiline code block `a` with block `b` leaving comments intact. |
|||
|
|||
Syntax of comments depends on the language of the code block. |
|||
Raises ValueError if the blocks are not compatible (different languages or different number of lines). |
|||
""" |
|||
|
|||
start_line = block_a["start_line_no"] |
|||
end_line_no = start_line + len(block_a["content"]) - 1 |
|||
|
|||
if block_a["lang"] != block_b["lang"]: |
|||
raise ValueError( |
|||
f"Code block (lines {start_line}-{end_line_no}) " |
|||
"has different language than the original block " |
|||
f"('{block_a['lang']}' vs '{block_b['lang']}')" |
|||
) |
|||
if len(block_a["content"]) != len(block_b["content"]): |
|||
raise ValueError( |
|||
f"Code block (lines {start_line}-{end_line_no}) " |
|||
"has different number of lines than the original block " |
|||
f"({len(block_a['content'])} vs {len(block_b['content'])})" |
|||
) |
|||
|
|||
block_language = block_a["lang"].lower() |
|||
if block_language in {"mermaid"}: |
|||
if block_a != block_b: |
|||
print( |
|||
f"Skipping mermaid code block replacement (lines {start_line}-{end_line_no}). " |
|||
"This should be checked manually." |
|||
) |
|||
return block_a["content"].copy() # We don't handle mermaid code blocks for now |
|||
|
|||
code_block: list[str] = [] |
|||
for line_a, line_b in zip(block_a["content"], block_b["content"]): |
|||
line_a_comment: Union[str, None] = None |
|||
line_b_comment: Union[str, None] = None |
|||
|
|||
# Handle comments based on language |
|||
if block_language in { |
|||
"python", |
|||
"py", |
|||
"sh", |
|||
"bash", |
|||
"dockerfile", |
|||
"requirements", |
|||
"gitignore", |
|||
"toml", |
|||
"yaml", |
|||
"yml", |
|||
"hash-style-comments", |
|||
}: |
|||
_line_a_code, line_a_comment = _split_hash_comment(line_a) |
|||
_line_b_code, line_b_comment = _split_hash_comment(line_b) |
|||
res_line = line_b |
|||
if line_b_comment: |
|||
res_line = res_line.replace(line_b_comment, line_a_comment, 1) |
|||
code_block.append(res_line) |
|||
elif block_language in {"console", "json", "slash-style-comments"}: |
|||
_line_a_code, line_a_comment = _split_slashes_comment(line_a) |
|||
_line_b_code, line_b_comment = _split_slashes_comment(line_b) |
|||
res_line = line_b |
|||
if line_b_comment: |
|||
res_line = res_line.replace(line_b_comment, line_a_comment, 1) |
|||
code_block.append(res_line) |
|||
else: |
|||
code_block.append(line_b) |
|||
|
|||
return code_block |
|||
|
|||
|
|||
def replace_multiline_code_blocks_in_text( |
|||
text: list[str], |
|||
code_blocks: list[MultilineCodeBlockInfo], |
|||
original_code_blocks: list[MultilineCodeBlockInfo], |
|||
) -> list[str]: |
|||
""" |
|||
Update each code block in `text` with the corresponding code block from |
|||
`original_code_blocks` with comments taken from `code_blocks`. |
|||
|
|||
Raises ValueError if the number, language, or shape of code blocks do not match. |
|||
""" |
|||
|
|||
if len(code_blocks) != len(original_code_blocks): |
|||
raise ValueError( |
|||
"Number of code blocks does not match the number in the original document " |
|||
f"({len(code_blocks)} vs {len(original_code_blocks)})" |
|||
) |
|||
|
|||
modified_text = text.copy() |
|||
for block, original_block in zip(code_blocks, original_code_blocks): |
|||
updated_content = replace_multiline_code_block(block, original_block) |
|||
|
|||
start_line_index = block["start_line_no"] - 1 |
|||
for i, updated_line in enumerate(updated_content): |
|||
modified_text[start_line_index + i] = updated_line |
|||
|
|||
return modified_text |
|||
|
|||
|
|||
# All checks |
|||
# -------------------------------------------------------------------------------------- |
|||
|
|||
|
|||
def check_translation( |
|||
doc_lines: list[str], |
|||
en_doc_lines: list[str], |
|||
lang_code: str, |
|||
auto_fix: bool, |
|||
path: str, |
|||
) -> list[str]: |
|||
# Fix code includes |
|||
en_code_includes = extract_code_includes(en_doc_lines) |
|||
doc_lines_with_placeholders = replace_code_includes_with_placeholders(doc_lines) |
|||
fixed_doc_lines = replace_placeholders_with_code_includes( |
|||
doc_lines_with_placeholders, en_code_includes |
|||
) |
|||
if auto_fix and (fixed_doc_lines != doc_lines): |
|||
print(f"Fixing code includes in: {path}") |
|||
doc_lines = fixed_doc_lines |
|||
|
|||
# Fix permalinks |
|||
en_permalinks = extract_header_permalinks(en_doc_lines) |
|||
doc_permalinks = extract_header_permalinks(doc_lines) |
|||
fixed_doc_lines = replace_header_permalinks( |
|||
doc_lines, doc_permalinks, en_permalinks |
|||
) |
|||
if auto_fix and (fixed_doc_lines != doc_lines): |
|||
print(f"Fixing header permalinks in: {path}") |
|||
doc_lines = fixed_doc_lines |
|||
|
|||
# Fix markdown links |
|||
en_markdown_links = extract_markdown_links(en_doc_lines) |
|||
doc_markdown_links = extract_markdown_links(doc_lines) |
|||
fixed_doc_lines = replace_markdown_links( |
|||
doc_lines, doc_markdown_links, en_markdown_links, lang_code |
|||
) |
|||
if auto_fix and (fixed_doc_lines != doc_lines): |
|||
print(f"Fixing markdown links in: {path}") |
|||
doc_lines = fixed_doc_lines |
|||
|
|||
# Fix HTML links |
|||
en_html_links = extract_html_links(en_doc_lines) |
|||
doc_html_links = extract_html_links(doc_lines) |
|||
fixed_doc_lines = replace_html_links( |
|||
doc_lines, doc_html_links, en_html_links, lang_code |
|||
) |
|||
if auto_fix and (fixed_doc_lines != doc_lines): |
|||
print(f"Fixing HTML links in: {path}") |
|||
doc_lines = fixed_doc_lines |
|||
|
|||
# Fix multiline code blocks |
|||
en_code_blocks = extract_multiline_code_blocks(en_doc_lines) |
|||
doc_code_blocks = extract_multiline_code_blocks(doc_lines) |
|||
fixed_doc_lines = replace_multiline_code_blocks_in_text( |
|||
doc_lines, doc_code_blocks, en_code_blocks |
|||
) |
|||
if auto_fix and (fixed_doc_lines != doc_lines): |
|||
print(f"Fixing multiline code blocks in: {path}") |
|||
doc_lines = fixed_doc_lines |
|||
|
|||
return doc_lines |
|||
@ -0,0 +1,528 @@ |
|||
### Your task |
|||
|
|||
Translate an English original content to a target language. |
|||
|
|||
The original content is written in Markdown, write the translation in Markdown as well. |
|||
|
|||
The original content will be surrounded by triple percentage signs (%%%). Do not include the triple percentage signs in the translation. |
|||
|
|||
### Technical terms in English |
|||
|
|||
For technical terms in English that don't have a common translation term, use the original term in English. |
|||
|
|||
### Content of code snippets |
|||
|
|||
Do not translate the content of code snippets, keep the original in English. For example, `list`, `dict`, keep them as is. |
|||
|
|||
### Content of code blocks |
|||
|
|||
Do not translate the content of code blocks, except for comments in the language which the code block uses. |
|||
|
|||
Examples: |
|||
|
|||
Source (English) - The code block is a bash code example with one comment: |
|||
|
|||
```bash |
|||
# Print greeting |
|||
echo "Hello, World!" |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
```bash |
|||
# Gruß ausgeben |
|||
echo "Hello, World!" |
|||
``` |
|||
|
|||
Source (English) - The code block is a console example containing HTML tags. No comments, so nothing to change here: |
|||
|
|||
```console |
|||
$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u> |
|||
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting server |
|||
Searching for package file structure |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
```console |
|||
$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u> |
|||
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting server |
|||
Searching for package file structure |
|||
``` |
|||
|
|||
Source (English) - The code block is a console example containing 5 comments: |
|||
|
|||
|
|||
```console |
|||
// Go to the home directory |
|||
$ cd |
|||
// Create a directory for all your code projects |
|||
$ mkdir code |
|||
// Enter into that code directory |
|||
$ cd code |
|||
// Create a directory for this project |
|||
$ mkdir awesome-project |
|||
// Enter into that project directory |
|||
$ cd awesome-project |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
```console |
|||
// Gehe zum Home-Verzeichnis |
|||
$ cd |
|||
// Erstelle ein Verzeichnis für alle Ihre Code-Projekte |
|||
$ mkdir code |
|||
// Gehe in dieses Code-Verzeichnis |
|||
$ cd code |
|||
// Erstelle ein Verzeichnis für dieses Projekt |
|||
$ mkdir awesome-project |
|||
// Gehe in dieses Projektverzeichnis |
|||
$ cd awesome-project |
|||
``` |
|||
|
|||
If there is an existing translation and its Mermaid diagram is in sync with the Mermaid diagram in the English source, except a few translated words, then use the Mermaid diagram of the existing translation. The human editor of the translation translated these words in the Mermaid diagram. Keep these translations, do not revert them back to the English source. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
subgraph global[global env] |
|||
harry-1[harry v1] |
|||
end |
|||
subgraph stone-project[philosophers-stone project] |
|||
stone(philosophers-stone) -->|requires| harry-1 |
|||
end |
|||
``` |
|||
|
|||
Existing translation (German) - has three translations: |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
subgraph global[globale Umgebung] |
|||
harry-1[harry v1] |
|||
end |
|||
subgraph stone-project[philosophers-stone-Projekt] |
|||
stone(philosophers-stone) -->|benötigt| harry-1 |
|||
end |
|||
``` |
|||
|
|||
Result (German) - you change nothing: |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
subgraph global[globale Umgebung] |
|||
harry-1[harry v1] |
|||
end |
|||
subgraph stone-project[philosophers-stone-Projekt] |
|||
stone(philosophers-stone) -->|benötigt| harry-1 |
|||
end |
|||
``` |
|||
|
|||
### Special blocks |
|||
|
|||
There are special blocks of notes, tips and others that look like: |
|||
|
|||
/// note |
|||
Here goes a note |
|||
/// |
|||
|
|||
To translate it, keep the same line and add the translation after a vertical bar. |
|||
|
|||
For example, if you were translating to Spanish, you would write: |
|||
|
|||
/// note | Nota |
|||
|
|||
Some examples in Spanish: |
|||
|
|||
Source (English): |
|||
|
|||
/// tip |
|||
|
|||
Result (Spanish): |
|||
|
|||
/// tip | Consejo |
|||
|
|||
Source (English): |
|||
|
|||
/// details | Preview |
|||
|
|||
Result (Spanish): |
|||
|
|||
/// details | Vista previa |
|||
|
|||
### Tab blocks |
|||
|
|||
There are special blocks surrounded by four slashes (////). They mark text, which will be rendered as part of a tab in the final document. The scheme is: |
|||
|
|||
//// tab | {tab title} |
|||
{tab content, may span many lines} |
|||
//// |
|||
|
|||
Keep everything before the vertical bar (|) as is, including the vertical bar. Translate the tab title. Translate the tab content, applying the rules you know. Keep the four block closing slashes as is. |
|||
|
|||
Examples: |
|||
|
|||
Source (English): |
|||
|
|||
//// tab | Python 3.8+ non-Annotated |
|||
Hello |
|||
//// |
|||
|
|||
Result (German): |
|||
|
|||
//// tab | Python 3.8+ nicht annotiert |
|||
Hallo |
|||
//// |
|||
|
|||
Source (English) - Here there is nothing to translate in the tab title: |
|||
|
|||
//// tab | Linux, macOS, Windows Bash |
|||
Hello again |
|||
//// |
|||
|
|||
Result (German): |
|||
|
|||
//// tab | Linux, macOS, Windows Bash |
|||
Hallo wieder |
|||
//// |
|||
|
|||
### Headings |
|||
|
|||
Every Markdown heading in the English text (all levels) ends with a part inside curly brackets. This part denotes the hash of this heading, which is used in links to this heading. In translations, translate the heading, but do not translate this hash part, so that links do not break. |
|||
|
|||
Examples of how to translate a heading: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
## Alternative API docs { #alternative-api-docs } |
|||
``` |
|||
|
|||
Result (Spanish): |
|||
|
|||
``` |
|||
## Documentación de la API alternativa { #alternative-api-docs } |
|||
``` |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
### Example { #example } |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
### Beispiel { #example } |
|||
``` |
|||
|
|||
### Links |
|||
|
|||
Use the following rules for links (apply both to Markdown-style links ([text](url)) and to HTML-style <a href="url">text</a> tags): |
|||
|
|||
- For relative URLs, only translate the link text. Do not translate the URL or its parts. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
[One of the fastest Python frameworks available](#performance) |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
[Eines der schnellsten verfügbaren Python-Frameworks](#performance) |
|||
``` |
|||
|
|||
- For absolute URLs which DO NOT start EXACTLY with https://fastapi.tiangolo.com, only translate the link text and leave the URL unchanged. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">SQLModel docs</a> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">SQLModel-Dokumentation</a> |
|||
``` |
|||
|
|||
- For absolute URLs which DO start EXACTLY with https://fastapi.tiangolo.com, only translate the link text and change the URL by adding the language code (https://fastapi.tiangolo.com/{language_code}[rest part of the url]). |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<a href="https://fastapi.tiangolo.com/tutorial/path-params/#documentation" class="external-link" target="_blank">Documentation</a> |
|||
``` |
|||
|
|||
Result (Spanish): |
|||
|
|||
``` |
|||
<a href="https://fastapi.tiangolo.com/es/tutorial/path-params/#documentation" class="external-link" target="_blank">Documentación</a> |
|||
``` |
|||
|
|||
- Do not add language codes for URLs that point to static assets (e.g., images, CSS, JavaScript). |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<a href="https://fastapi.tiangolo.com/img/something.jpg" class="external-link" target="_blank">Something</a> |
|||
``` |
|||
|
|||
Result (Spanish): |
|||
|
|||
``` |
|||
<a href="https://fastapi.tiangolo.com/img/something.jpg" class="external-link" target="_blank">Algo</a> |
|||
``` |
|||
|
|||
- For internal links, only translate link text. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
[Create Pull Requests](help-fastapi.md#create-a-pull-request){.internal-link target=_blank} |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
[Pull Requests erzeugen](help-fastapi.md#create-a-pull-request){.internal-link target=_blank} |
|||
``` |
|||
|
|||
- Do not translate anchor fragments in links (the part after `#`), as they must remain the same to work correctly. |
|||
|
|||
- If an existing translation has a link with an anchor fragment different to the anchor fragment in the English source, then this is an error. Fix this by using the anchor fragment of the English source. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
[Body - Multiple Parameters: Singular values in body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank} |
|||
``` |
|||
|
|||
Existing wrong translation (German) - notice the wrongly translated anchor fragment: |
|||
|
|||
``` |
|||
[Body - Mehrere Parameter: Einfache Werte im Body](body-multiple-params.md#einzelne-werte-im-body){.internal-link target=_blank}. |
|||
``` |
|||
|
|||
Result (German) - you fix the anchor fragment: |
|||
|
|||
``` |
|||
[Body - Mehrere Parameter: Einfache Werte im Body](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}. |
|||
``` |
|||
|
|||
- Do not add anchor fragments at will, even if this makes sense. If the English source has no anchor, don't add one. |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
Create a [virtual environment](../virtual-environments.md){.internal-link target=_blank} |
|||
``` |
|||
|
|||
Wrong translation in German - Anchor added to the URL. |
|||
|
|||
``` |
|||
Erstelle eine [virtuelle Umgebung](../virtual-environments.md#create-a-virtual-environment){.internal-link target=_blank} |
|||
``` |
|||
|
|||
Good translation (German) - URL stays like in the English source. |
|||
|
|||
``` |
|||
Erstelle eine [Virtuelle Umgebung](../virtual-environments.md){.internal-link target=_blank} |
|||
``` |
|||
|
|||
### HTML abbr elements |
|||
|
|||
Translate HTML abbr elements (`<abbr title="description">text</abbr>`) as follows: |
|||
|
|||
- If the text surrounded by the abbr element is an abbreviation (the text may be surrounded by further HTML or Markdown markup or quotes, for example <code>text</code> or `text` or "text", ignore that further markup when deciding if the text is an abbreviation), and if the description (the text inside the title attribute) contains the full phrase for this abbreviation, then append a dash (-) to the full phrase, followed by the translation of the full phrase. |
|||
|
|||
Conversion scheme: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="{full phrase}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Result: |
|||
|
|||
``` |
|||
<abbr title="{full phrase} - {translation of full phrase}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Examples: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="Internet of Things">IoT</abbr> |
|||
<abbr title="Central Processing Unit">CPU</abbr> |
|||
<abbr title="too long; didn't read"><strong>TL;DR:</strong></abbr> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<abbr title="Internet of Things - Internet der Dinge">IoT</abbr> |
|||
<abbr title="Central Processing Unit - Zentrale Verarbeitungseinheit">CPU</abbr> |
|||
<abbr title="too long; didn't read - zu lang; hab's nicht gelesen"><strong>TL;DR:</strong></abbr> |
|||
``` |
|||
|
|||
- If the language to which you translate mostly uses the letters of the ASCII char set (for example Spanish, French, German, but not Russian, Chinese) and if the translation of the full phrase is identical to, or starts with the same letters as the original full phrase, then only give the translation of the full phrase. |
|||
|
|||
Conversion scheme: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="{full phrase}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Result: |
|||
|
|||
``` |
|||
<abbr title="{translation of full phrase}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Examples: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="JSON Web Tokens">JWT</abbr> |
|||
<abbr title="Enumeration">Enum</abbr> |
|||
<abbr title="Asynchronous Server Gateway Interface">ASGI</abbr> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<abbr title="JSON Web Tokens">JWT</abbr> |
|||
<abbr title="Enumeration">Enum</abbr> |
|||
<abbr title="Asynchrones Server-Gateway-Interface">ASGI</abbr> |
|||
``` |
|||
|
|||
- If the description is not a full phrase for an abbreviation which the abbr element surrounds, but some other information, then just translate the description. |
|||
|
|||
Conversion scheme: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="{description}">{text}</abbr> |
|||
``` |
|||
|
|||
Result: |
|||
|
|||
``` |
|||
<abbr title="{translation of description}">{translation of text}</abbr> |
|||
``` |
|||
|
|||
Examples: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="also known as: endpoints, routes">path</abbr> |
|||
<abbr title="a program that checks for code errors">linter</abbr> |
|||
<abbr title="converting the string that comes from an HTTP request into Python data">parsing</abbr> |
|||
<abbr title="before 2023-03">0.95.0</abbr> |
|||
<abbr title="2023-08-26">at the time of writing this</abbr> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<abbr title="auch bekannt als: Endpunkte, Routen">Pfad</abbr> |
|||
<abbr title="Programm das auf Fehler im Code prüft">Linter</abbr> |
|||
<abbr title="Konvertieren des Strings eines HTTP-Requests in Python-Daten">Parsen</abbr> |
|||
<abbr title="vor 2023-03">0.95.0</abbr> |
|||
<abbr title="2023-08-26">zum Zeitpunkt als das hier geschrieben wurde</abbr> |
|||
``` |
|||
|
|||
- If the text surrounded by the abbr element is an abbreviation and the description contains both the full phrase for that abbreviation, and other information, separated by a colon (`:`), then append a dash (`-`) and the translation of the full phrase to the original full phrase and translate the other information. |
|||
|
|||
Conversion scheme: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="{full phrase}: {other information}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Result: |
|||
|
|||
``` |
|||
<abbr title="{full phrase} - {translation of full phrase}: {translation of other information}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Examples: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="Input/Output: disk reading or writing, network communication.">I/O</abbr> |
|||
<abbr title="Content Delivery Network: service, that provides static files.">CDN</abbr> |
|||
<abbr title="Integrated Development Environment: similar to a code editor">IDE</abbr> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<abbr title="Input/Output - Eingabe/Ausgabe: Lesen oder Schreiben auf der Festplatte, Netzwerkkommunikation.">I/O</abbr> |
|||
<abbr title="Content Delivery Network - Inhalte auslieferndes Netzwerk: Dienst, der statische Dateien bereitstellt.">CDN</abbr> |
|||
<abbr title="Integrated Development Environment - Integrierte Entwicklungsumgebung: Ähnlich einem Code-Editor">IDE</abbr> |
|||
``` |
|||
|
|||
- You can leave the original full phrase away, if the translated full phrase is identical or starts with the same letters as the original full phrase. |
|||
|
|||
Conversion scheme: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="{full phrase}: {information}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Result: |
|||
|
|||
``` |
|||
<abbr title="{translation of full phrase}: {translation of information}">{abbreviation}</abbr> |
|||
``` |
|||
|
|||
Example: |
|||
|
|||
Source (English): |
|||
|
|||
``` |
|||
<abbr title="Object Relational Mapper: a fancy term for a library where some classes represent SQL tables and instances represent rows in those tables">ORM</abbr> |
|||
``` |
|||
|
|||
Result (German): |
|||
|
|||
``` |
|||
<abbr title="Objektrelationaler Mapper: Ein Fachbegriff für eine Bibliothek, in der einige Klassen SQL-Tabellen und Instanzen Zeilen in diesen Tabellen darstellen">ORM</abbr> |
|||
``` |
|||
|
|||
- If there is an existing translation, and it has ADDITIONAL abbr elements in a sentence, and these additional abbr elements do not exist in the related sentence in the English text, then KEEP those additional abbr elements in the translation. Do not remove them. Except when you remove the whole sentence from the translation, because the whole sentence was removed from the English text, then also remove the abbr element. The reasoning for this rule is, that such additional abbr elements are manually added by the human editor of the translation, in order to translate or explain an English word to the human readers of the translation. These additional abbr elements would not make sense in the English text, but they do make sense in the translation. So keep them in the translation, even though they are not part of the English text. This rule only applies to abbr elements. |
|||
|
|||
- Apply above rules also when there is an existing translation! Make sure that all title attributes in abbr elements get properly translated or updated, using the schemes given above. However, leave the ADDITIONAL abbr's described above alone. Do not change their formatting or content. |
|||
@ -0,0 +1,42 @@ |
|||
import shutil |
|||
import sys |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
skip_on_windows = pytest.mark.skipif( |
|||
sys.platform == "win32", reason="Skipping on Windows" |
|||
) |
|||
|
|||
|
|||
def pytest_collection_modifyitems(items: list[pytest.Item]) -> None: |
|||
for item in items: |
|||
item.add_marker(skip_on_windows) |
|||
|
|||
|
|||
@pytest.fixture(name="runner") |
|||
def get_runner(): |
|||
runner = CliRunner() |
|||
with runner.isolated_filesystem(): |
|||
yield runner |
|||
|
|||
|
|||
@pytest.fixture(name="root_dir") |
|||
def prepare_paths(runner): |
|||
docs_dir = Path("docs") |
|||
en_docs_dir = docs_dir / "en" / "docs" |
|||
lang_docs_dir = docs_dir / "lang" / "docs" |
|||
en_docs_dir.mkdir(parents=True, exist_ok=True) |
|||
lang_docs_dir.mkdir(parents=True, exist_ok=True) |
|||
yield Path.cwd() |
|||
|
|||
|
|||
@pytest.fixture |
|||
def copy_test_files(root_dir: Path, request: pytest.FixtureRequest): |
|||
en_file_path = Path(request.param[0]) |
|||
translation_file_path = Path(request.param[1]) |
|||
shutil.copy(str(en_file_path), str(root_dir / "docs" / "en" / "docs" / "doc.md")) |
|||
shutil.copy( |
|||
str(translation_file_path), str(root_dir / "docs" / "lang" / "docs" / "doc.md") |
|||
) |
|||
@ -0,0 +1,44 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
```toml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Mermaid diagram |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,45 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
```toml |
|||
# Extra line |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,45 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
The following block is missing first line: |
|||
|
|||
```toml |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,44 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
```toml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,44 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
```toml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|требует| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,50 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
```toml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
Extra code block |
|||
|
|||
``` |
|||
$ cd my_project |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,41 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
Missing code block... |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,46 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
The following block has wrong language code (should be TOML): |
|||
|
|||
```yaml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,46 @@ |
|||
# Code blocks { #code-blocks } |
|||
|
|||
Some text |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
Some more text |
|||
|
|||
The following block has wrong language code (should be TOML): |
|||
|
|||
``` |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
And more text |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
And even more text |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
Диаграма Mermaid |
|||
|
|||
```mermaid |
|||
flowchart LR |
|||
stone(philosophers-stone) -->|requires| harry-1[harry v1] |
|||
``` |
|||
@ -0,0 +1,58 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_code_blocks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_lines_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_lines_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Code block (lines 14-18) has different number of lines than the original block (5 vs 4)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_lines_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
# assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_lines_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Code block (lines 16-18) has different number of lines than the original block (3 vs 4)" |
|||
) in result.output |
|||
@ -0,0 +1,59 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_code_blocks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_mermaid_translated.md")], |
|||
indirect=True, |
|||
) |
|||
def test_translated(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 0, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path( |
|||
f"{data_path}/translated_doc_mermaid_translated.md" |
|||
).read_text("utf-8") |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert ( |
|||
"Skipping mermaid code block replacement (lines 41-44). This should be checked manually." |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[ |
|||
( |
|||
f"{data_path}/en_doc.md", |
|||
f"{data_path}/translated_doc_mermaid_not_translated.md", |
|||
) |
|||
], |
|||
indirect=True, |
|||
) |
|||
def test_not_translated(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 0, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path( |
|||
f"{data_path}/translated_doc_mermaid_not_translated.md" |
|||
).read_text("utf-8") |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert ("Skipping mermaid code block replacement") not in result.output |
|||
@ -0,0 +1,60 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_code_blocks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of code blocks does not match the number " |
|||
"in the original document (6 vs 5)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
# assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of code blocks does not match the number " |
|||
"in the original document (4 vs 5)" |
|||
) in result.output |
|||
@ -0,0 +1,58 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_code_blocks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_wrong_lang_code.md")], |
|||
indirect=True, |
|||
) |
|||
def test_wrong_lang_code_1(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_wrong_lang_code.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Code block (lines 16-19) has different language than the original block ('yaml' vs 'toml')" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_wrong_lang_code_2.md")], |
|||
indirect=True, |
|||
) |
|||
def test_wrong_lang_code_2(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path( |
|||
f"{data_path}/translated_doc_wrong_lang_code_2.md" |
|||
).read_text("utf-8") |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Code block (lines 16-19) has different language than the original block ('' vs 'toml')" |
|||
) in result.output |
|||
@ -0,0 +1,13 @@ |
|||
# Header |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
Some text |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
Some more text |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
And even more text |
|||
@ -0,0 +1,15 @@ |
|||
# Header |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
Some text |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
Some more text |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
And even more text |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py *} |
|||
@ -0,0 +1,13 @@ |
|||
# Header |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
Some text |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
Some more text |
|||
|
|||
... |
|||
|
|||
And even more text |
|||
@ -0,0 +1,60 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_code_includes/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of code include placeholders does not match the number of code includes " |
|||
"in the original document (4 vs 3)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of code include placeholders does not match the number of code includes " |
|||
"in the original document (2 vs 3)" |
|||
) in result.output |
|||
@ -0,0 +1,244 @@ |
|||
# Test translation fixer tool { #test-translation-fixer } |
|||
|
|||
## Code blocks with and without comments { #code-blocks-with-and-without-comments } |
|||
|
|||
This is a test page for the translation fixer tool. |
|||
|
|||
### Code blocks with comments { #code-blocks-with-comments } |
|||
|
|||
The following code blocks include comments in different styles. |
|||
Fixer tool should fix content, but preserve comments correctly. |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
# Comment with indentation |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
```toml |
|||
# This is a sample TOML code block |
|||
title = "TOML Example" # Title of the document |
|||
``` |
|||
|
|||
```console |
|||
// Use the command "live" and pass the language code as a CLI argument |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
```json |
|||
{ |
|||
// This is a sample JSON code block |
|||
"greeting": "Hello, world!" // Greeting |
|||
} |
|||
``` |
|||
|
|||
|
|||
### Code blocks with comments where language uses different comment styles { #code-blocks-with-different-comment-styles } |
|||
|
|||
The following code blocks include comments in different styles based on the language. |
|||
Fixer tool will not preserve comments in these blocks. |
|||
|
|||
```json |
|||
{ |
|||
# This is a sample JSON code block |
|||
"greeting": "Hello, world!" # Print greeting |
|||
} |
|||
``` |
|||
|
|||
```console |
|||
# This is a sample console code block |
|||
$ echo "Hello, world!" # Print greeting |
|||
``` |
|||
|
|||
```toml |
|||
// This is a sample TOML code block |
|||
title = "TOML Example" // Title of the document |
|||
``` |
|||
|
|||
|
|||
### Code blocks with comments with unsupported languages or without language specified { #code-blocks-with-unsupported-languages } |
|||
|
|||
The following code blocks use unsupported languages for comment preservation. |
|||
Fixer tool will not preserve comments in these blocks. |
|||
|
|||
```javascript |
|||
// This is a sample JavaScript code block |
|||
console.log("Hello, world!"); // Print greeting |
|||
``` |
|||
|
|||
``` |
|||
# This is a sample console code block |
|||
$ echo "Hello, world!" # Print greeting |
|||
``` |
|||
|
|||
``` |
|||
// This is a sample console code block |
|||
$ echo "Hello, world!" // Print greeting |
|||
``` |
|||
|
|||
|
|||
### Code blocks with comments that don't follow pattern { #code-blocks-with-comments-without-pattern } |
|||
|
|||
Fixer tool expects comments that follow specific pattern: |
|||
|
|||
- For hash-style comments: comment starts with `# ` (hash following by whitespace) in the beginning of the string or after a whitespace. |
|||
- For slash-style comments: comment starts with `// ` (two slashes following by whitespace) in the beginning of the string or after a whitespace. |
|||
|
|||
If comment doesn't follow this pattern, fixer tool will not preserve it. |
|||
|
|||
```python |
|||
#Function declaration |
|||
def hello_world():# Print greeting |
|||
print("Hello, world!") #Print greeting without space after hash |
|||
``` |
|||
|
|||
```console |
|||
//Function declaration |
|||
def hello_world():// Print greeting |
|||
print("Hello, world!") //Print greeting without space after slashes |
|||
``` |
|||
|
|||
## Code blocks with quadruple backticks { #code-blocks-with-quadruple-backticks } |
|||
|
|||
The following code block uses quadruple backticks. |
|||
|
|||
````python |
|||
# Hello world function |
|||
def hello_world(): |
|||
print("Hello, world!") # Print greeting |
|||
```` |
|||
|
|||
### Backticks number mismatch is fixable { #backticks-number-mismatch-is-fixable } |
|||
|
|||
The following code block has triple backticks in the original document, but quadruple backticks in the translated document. |
|||
It will be fixed by the fixer tool (will convert to triple backticks). |
|||
|
|||
```Python |
|||
# Some Python code |
|||
``` |
|||
|
|||
### Triple backticks inside quadruple backticks { #triple-backticks-inside-quadruple-backticks } |
|||
|
|||
Comments inside nested code block will NOT be preserved. |
|||
|
|||
```` |
|||
Here is a code block with quadruple backticks that contains triple backticks inside: |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
```` |
|||
|
|||
# Code includes { #code-includes } |
|||
|
|||
## Simple code includes { #simple-code-includes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py *} |
|||
|
|||
|
|||
## Code includes with highlighting { #code-includes-with-highlighting } |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial006_py39.py hl[10] *} |
|||
|
|||
|
|||
## Code includes with line ranges { #code-includes-with-line-ranges } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] *} |
|||
|
|||
|
|||
## Code includes with line ranges and highlighting { #code-includes-with-line-ranges-and-highlighting } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial015_an_py310.py ln[10:15] hl[12:14] *} |
|||
|
|||
|
|||
## Code includes qith title { #code-includes-with-title } |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
## Code includes with unknown attributes { #code-includes-with-unknown-attributes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py unknown[123] *} |
|||
|
|||
## Some more code includes to test fixing { #some-more-code-includes-to-test-fixing } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
|
|||
|
|||
# Links { #links } |
|||
|
|||
## Markdown-style links { #markdown-style-links } |
|||
|
|||
This is a [Markdown link](https://example.com) to an external site. |
|||
|
|||
This is a link with attributes: [**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank} |
|||
|
|||
This is a link to the main FastAPI site: [FastAPI](https://fastapi.tiangolo.com) - tool should add language code to the URL. |
|||
|
|||
This is a link to one of the pages on FastAPI site: [How to](https://fastapi.tiangolo.com/how-to/) - tool should add language code to the URL. |
|||
|
|||
Link to test wrong attribute: [**FastAPI** Project Generators](project-generation.md){.internal-link} - tool should fix the attribute. |
|||
|
|||
Link with a title: [Example](https://example.com "Example site") - URL will be fixed, title preserved. |
|||
|
|||
### Markdown link to static assets { #markdown-link-to-static-assets } |
|||
|
|||
These are links to static assets: |
|||
|
|||
* [FastAPI Logo](https://fastapi.tiangolo.com/img/fastapi-logo.png) |
|||
* [FastAPI CSS](https://fastapi.tiangolo.com/css/fastapi.css) |
|||
* [FastAPI JS](https://fastapi.tiangolo.com/js/fastapi.js) |
|||
|
|||
Tool should NOT add language code to their URLs. |
|||
|
|||
## HTML-style links { #html-style-links } |
|||
|
|||
This is an <a href="https://example.com" target="_blank" class="external-link">HTML link</a> to an external site. |
|||
|
|||
This is an <a href="https://fastapi.tiangolo.com">link to the main FastAPI site</a> - tool should add language code to the URL. |
|||
|
|||
This is an <a href="https://fastapi.tiangolo.com/how-to/">link to one of the pages on FastAPI site</a> - tool should add language code to the URL. |
|||
|
|||
Link to test wrong attribute: <a href="project-generation.md" class="internal-link">**FastAPI** Project Generators</a> - tool should fix the attribute. |
|||
|
|||
### HTML links to static assets { #html-links-to-static-assets } |
|||
|
|||
These are links to static assets: |
|||
|
|||
* <a href="https://fastapi.tiangolo.com/img/fastapi-logo.png">FastAPI Logo</a> |
|||
* <a href="https://fastapi.tiangolo.com/css/fastapi.css">FastAPI CSS</a> |
|||
* <a href="https://fastapi.tiangolo.com/js/fastapi.js">FastAPI JS</a> |
|||
|
|||
Tool should NOT add language code to their URLs. |
|||
|
|||
# Header (with HTML link to <a href="https://tiangolo.com">tiangolo.com</a>) { #header-with-html-link-to-tiangolo-com } |
|||
|
|||
#Not a header |
|||
|
|||
```Python |
|||
# Also not a header |
|||
``` |
|||
|
|||
Some text |
|||
@ -0,0 +1,240 @@ |
|||
# Тестовый инструмент исправления переводов { #test-translation-fixer } |
|||
|
|||
## Блоки кода с комментариями и без комментариев { #code-blocks-with-and-without-comments } |
|||
|
|||
Это тестовая страница для инструмента исправления переводов. |
|||
|
|||
### Блоки кода с комментариями { #code-blocks-with-comments } |
|||
|
|||
Следующие блоки кода содержат комментарии в разных стилях. |
|||
Инструмент исправления должен исправлять содержимое, но корректно сохранять комментарии. |
|||
|
|||
```python |
|||
# Это пример блока кода на Python |
|||
def hello_world(): |
|||
# Комментарий с отступом |
|||
print("Hello, world!") # Печать приветствия |
|||
``` |
|||
|
|||
```toml |
|||
# Это пример блока кода на TOML |
|||
title = "TOML Example" # Заголовок документа |
|||
``` |
|||
|
|||
```console |
|||
// Используйте команду "live" и передайте код языка в качестве аргумента CLI |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
```json |
|||
{ |
|||
// Это пример блока кода на JSON |
|||
"greeting": "Hello, world!" // Печать приветствия |
|||
} |
|||
``` |
|||
|
|||
|
|||
### Блоки кода с комментариями, где язык использует другие стили комментариев { #code-blocks-with-different-comment-styles } |
|||
|
|||
Следующие блоки кода содержат комментарии в разных стилях в зависимости от языка. |
|||
Инструмент исправления не будет сохранять комментарии в этих блоках. |
|||
|
|||
```json |
|||
{ |
|||
# Это пример блока кода на JSON |
|||
"greeting": "Hello, world!" # Печать приветствия |
|||
} |
|||
``` |
|||
|
|||
```console |
|||
# Это пример блока кода консоли |
|||
$ echo "Hello, world!" # Печать приветствия |
|||
``` |
|||
|
|||
```toml |
|||
// Это пример блока кода на TOML |
|||
title = "TOML Example" // Заголовок документа |
|||
``` |
|||
|
|||
### Блоки кода с комментариями на неподдерживаемых языках или без указания языка { #code-blocks-with-unsupported-languages } |
|||
|
|||
Следующие блоки кода используют неподдерживаемые языки для сохранения комментариев. |
|||
Инструмент исправления не будет сохранять комментарии в этих блоках. |
|||
|
|||
```javascript |
|||
// Это пример блока кода на JavaScript |
|||
console.log("Hello, world!"); // Печать приветствия |
|||
``` |
|||
|
|||
``` |
|||
# Это пример блока кода консоли |
|||
$ echo "Hello, world!" # Печать приветствия |
|||
``` |
|||
|
|||
``` |
|||
// Это пример блока кода консоли |
|||
$ echo "Hello, world!" // Печать приветствия |
|||
``` |
|||
|
|||
### Блоки кода с комментариями, которые не соответствуют шаблону { #code-blocks-with-comments-without-pattern } |
|||
|
|||
Инструмент исправления ожидает комментарии, которые соответствуют определённому шаблону: |
|||
|
|||
- Для комментариев в стиле с решёткой: комментарий начинается с `# ` (решётка, затем пробел) в начале строки или после пробела. |
|||
- Для комментариев в стиле со слешами: комментарий начинается с `// ` (два слеша, затем пробел) в начале строки или после пробела. |
|||
|
|||
Если комментарий не соответствует этому шаблону, инструмент исправления не будет его сохранять. |
|||
|
|||
```python |
|||
#Объявление функции |
|||
def hello_world():# Печать приветствия |
|||
print("Hello, world!") #Печать приветствия без пробела после решётки |
|||
``` |
|||
|
|||
```console |
|||
//Объявление функции |
|||
def hello_world():// Печать приветствия |
|||
print("Hello, world!") //Печать приветствия без пробела после слешей |
|||
``` |
|||
|
|||
## Блок кода с четырёхкратными обратными кавычками { #code-blocks-with-quadruple-backticks } |
|||
|
|||
Следующий блок кода содержит четырёхкратные обратные кавычки. |
|||
|
|||
````python |
|||
# Функция приветствия |
|||
def hello_world(): |
|||
print("Hello, world") # Печать приветствия |
|||
```` |
|||
|
|||
### Несоответствие обратных кавычек фиксится { #backticks-number-mismatch-is-fixable } |
|||
|
|||
Следующий блок кода имеет тройные обратные кавычки в оригинальном документе, но четырёхкратные обратные кавычки в переведённом документе. |
|||
Это будет исправлено инструментом исправления (будет преобразовано в тройные обратные кавычки). |
|||
|
|||
````Python |
|||
# Немного кода на Python |
|||
```` |
|||
|
|||
### Блок кода в тройных обратных кавычка внутри блока кода в четырёхкратных обратных кавычках { #triple-backticks-inside-quadruple-backticks } |
|||
|
|||
Комментарии внутри вложенного блока кода в тройных обратных кавычках НЕ БУДУТ сохранены. |
|||
|
|||
```` |
|||
Here is a code block with quadruple backticks that contains triple backticks inside: |
|||
|
|||
```python |
|||
# Этот комментарий НЕ будет сохранён |
|||
def hello_world(): |
|||
print("Hello, world") # Как и этот комментарий |
|||
``` |
|||
|
|||
```` |
|||
|
|||
# Включения кода { #code-includes } |
|||
|
|||
## Простые включения кода { #simple-code-includes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py *} |
|||
|
|||
|
|||
## Включения кода с подсветкой { #code-includes-with-highlighting } |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial006_py39.py hl[10] *} |
|||
|
|||
|
|||
## Включения кода с диапазонами строк { #code-includes-with-line-ranges } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] *} |
|||
|
|||
|
|||
## Включения кода с диапазонами строк и подсветкой { #code-includes-with-line-ranges-and-highlighting } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial015_an_py310.py ln[10:15] hl[12:14] *} |
|||
|
|||
|
|||
## Включения кода с заголовком { #code-includes-with-title } |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
## Включения кода с неизвестными атрибутами { #code-includes-with-unknown-attributes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py unknown[123] *} |
|||
|
|||
## Ещё включения кода для тестирования исправления { #some-more-code-includes-to-test-fixing } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19 : 21] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/wrong.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[1:30] hl[1:10] *} |
|||
|
|||
# Ссылки { #links } |
|||
|
|||
## Ссылки в стиле Markdown { #markdown-style-links } |
|||
|
|||
Это [Markdown-ссылка](https://example.com) на внешний сайт. |
|||
|
|||
Это ссылка с атрибутами: [**FastAPI** генераторы проектов](project-generation.md){.internal-link target=_blank} |
|||
|
|||
Это ссылка на основной сайт FastAPI: [FastAPI](https://fastapi.tiangolo.com) — инструмент должен добавить код языка в URL. |
|||
|
|||
Это ссылка на одну из страниц на сайте FastAPI: [How to](https://fastapi.tiangolo.com/how-to) — инструмент должен добавить код языка в URL. |
|||
|
|||
Ссылка для тестирования неправильного атрибута: [**FastAPI** генераторы проектов](project-generation.md){.external-link} - инструмент должен исправить атрибут. |
|||
|
|||
Ссылка с заголовком: [Пример](http://example.com/ "Сайт для примера") - URL будет исправлен инструментом, заголовок сохранится. |
|||
|
|||
### Markdown ссылки на статические ресурсы { #markdown-link-to-static-assets } |
|||
|
|||
Это ссылки на статические ресурсы: |
|||
|
|||
* [FastAPI Logo](https://fastapi.tiangolo.com/img/fastapi-logo.png) |
|||
* [FastAPI CSS](https://fastapi.tiangolo.com/css/fastapi.css) |
|||
* [FastAPI JS](https://fastapi.tiangolo.com/js/fastapi.js) |
|||
|
|||
Инструмент НЕ должен добавлять код языка в их URL. |
|||
|
|||
## Ссылки в стиле HTML { #html-style-links } |
|||
|
|||
Это <a href="https://example.com" target="_blank" class="external-link">HTML-ссылка</a> на внешний сайт. |
|||
|
|||
Это <a href="https://fastapi.tiangolo.com">ссылка на основной сайт FastAPI</a> — инструмент должен добавить код языка в URL. |
|||
|
|||
Это <a href="https://fastapi.tiangolo.com/how-to/">ссылка на одну из страниц на сайте FastAPI</a> — инструмент должен добавить код языка в URL. |
|||
|
|||
Ссылка для тестирования неправильного атрибута: <a href="project-generation.md" class="external-link">**FastAPI** генераторы проектов</a> - инструмент должен исправить атрибут. |
|||
|
|||
### HTML ссылки на статические ресурсы { #html-links-to-static-assets } |
|||
|
|||
Это ссылки на статические ресурсы: |
|||
|
|||
* <a href="https://fastapi.tiangolo.com/img/fastapi-logo.png">FastAPI Logo</a> |
|||
* <a href="https://fastapi.tiangolo.com/css/fastapi.css">FastAPI CSS</a> |
|||
* <a href="https://fastapi.tiangolo.com/js/fastapi.js">FastAPI JS</a> |
|||
|
|||
Инструмент НЕ должен добавлять код языка в их URL. |
|||
|
|||
# Заголовок (с HTML ссылкой на <a href="https://tiangolo.com">tiangolo.com</a>) { #header-5 } |
|||
|
|||
#Не заголовок |
|||
|
|||
```Python |
|||
# Также не заголовок |
|||
``` |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,240 @@ |
|||
# Тестовый инструмент исправления переводов { #test-translation-fixer } |
|||
|
|||
## Блоки кода с комментариями и без комментариев { #code-blocks-with-and-without-comments } |
|||
|
|||
Это тестовая страница для инструмента исправления переводов. |
|||
|
|||
### Блоки кода с комментариями { #code-blocks-with-comments } |
|||
|
|||
Следующие блоки кода содержат комментарии в разных стилях. |
|||
Инструмент исправления должен исправлять содержимое, но корректно сохранять комментарии. |
|||
|
|||
```python |
|||
# Это пример блока кода на Python |
|||
def hello_world(): |
|||
# Комментарий с отступом |
|||
print("Hello, world!") # Печать приветствия |
|||
``` |
|||
|
|||
```toml |
|||
# Это пример блока кода на TOML |
|||
title = "TOML Example" # Заголовок документа |
|||
``` |
|||
|
|||
```console |
|||
// Используйте команду "live" и передайте код языка в качестве аргумента CLI |
|||
$ python ./scripts/docs.py live es |
|||
|
|||
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
|||
<span style="color: green;">[INFO]</span> Start watching changes |
|||
<span style="color: green;">[INFO]</span> Start detecting changes |
|||
``` |
|||
|
|||
```json |
|||
{ |
|||
// Это пример блока кода на JSON |
|||
"greeting": "Hello, world!" // Печать приветствия |
|||
} |
|||
``` |
|||
|
|||
|
|||
### Блоки кода с комментариями, где язык использует другие стили комментариев { #code-blocks-with-different-comment-styles } |
|||
|
|||
Следующие блоки кода содержат комментарии в разных стилях в зависимости от языка. |
|||
Инструмент исправления не будет сохранять комментарии в этих блоках. |
|||
|
|||
```json |
|||
{ |
|||
# This is a sample JSON code block |
|||
"greeting": "Hello, world!" # Print greeting |
|||
} |
|||
``` |
|||
|
|||
```console |
|||
# This is a sample console code block |
|||
$ echo "Hello, world!" # Print greeting |
|||
``` |
|||
|
|||
```toml |
|||
// This is a sample TOML code block |
|||
title = "TOML Example" // Title of the document |
|||
``` |
|||
|
|||
### Блоки кода с комментариями на неподдерживаемых языках или без указания языка { #code-blocks-with-unsupported-languages } |
|||
|
|||
Следующие блоки кода используют неподдерживаемые языки для сохранения комментариев. |
|||
Инструмент исправления не будет сохранять комментарии в этих блоках. |
|||
|
|||
```javascript |
|||
// This is a sample JavaScript code block |
|||
console.log("Hello, world!"); // Print greeting |
|||
``` |
|||
|
|||
``` |
|||
# This is a sample console code block |
|||
$ echo "Hello, world!" # Print greeting |
|||
``` |
|||
|
|||
``` |
|||
// This is a sample console code block |
|||
$ echo "Hello, world!" // Print greeting |
|||
``` |
|||
|
|||
### Блоки кода с комментариями, которые не соответствуют шаблону { #code-blocks-with-comments-without-pattern } |
|||
|
|||
Инструмент исправления ожидает комментарии, которые соответствуют определённому шаблону: |
|||
|
|||
- Для комментариев в стиле с решёткой: комментарий начинается с `# ` (решётка, затем пробел) в начале строки или после пробела. |
|||
- Для комментариев в стиле со слешами: комментарий начинается с `// ` (два слеша, затем пробел) в начале строки или после пробела. |
|||
|
|||
Если комментарий не соответствует этому шаблону, инструмент исправления не будет его сохранять. |
|||
|
|||
```python |
|||
#Function declaration |
|||
def hello_world():# Print greeting |
|||
print("Hello, world!") #Print greeting without space after hash |
|||
``` |
|||
|
|||
```console |
|||
//Function declaration |
|||
def hello_world():// Print greeting |
|||
print("Hello, world!") //Print greeting without space after slashes |
|||
``` |
|||
|
|||
## Блок кода с четырёхкратными обратными кавычками { #code-blocks-with-quadruple-backticks } |
|||
|
|||
Следующий блок кода содержит четырёхкратные обратные кавычки. |
|||
|
|||
````python |
|||
# Функция приветствия |
|||
def hello_world(): |
|||
print("Hello, world!") # Печать приветствия |
|||
```` |
|||
|
|||
### Несоответствие обратных кавычек фиксится { #backticks-number-mismatch-is-fixable } |
|||
|
|||
Следующий блок кода имеет тройные обратные кавычки в оригинальном документе, но четырёхкратные обратные кавычки в переведённом документе. |
|||
Это будет исправлено инструментом исправления (будет преобразовано в тройные обратные кавычки). |
|||
|
|||
```Python |
|||
# Немного кода на Python |
|||
``` |
|||
|
|||
### Блок кода в тройных обратных кавычка внутри блока кода в четырёхкратных обратных кавычках { #triple-backticks-inside-quadruple-backticks } |
|||
|
|||
Комментарии внутри вложенного блока кода в тройных обратных кавычках НЕ БУДУТ сохранены. |
|||
|
|||
```` |
|||
Here is a code block with quadruple backticks that contains triple backticks inside: |
|||
|
|||
```python |
|||
# This is a sample Python code block |
|||
def hello_world(): |
|||
print("Hello, world!") # Print greeting |
|||
``` |
|||
|
|||
```` |
|||
|
|||
# Включения кода { #code-includes } |
|||
|
|||
## Простые включения кода { #simple-code-includes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py *} |
|||
|
|||
|
|||
## Включения кода с подсветкой { #code-includes-with-highlighting } |
|||
|
|||
{* ../../docs_src/python_types/tutorial002_py39.py hl[1] *} |
|||
|
|||
{* ../../docs_src/python_types/tutorial006_py39.py hl[10] *} |
|||
|
|||
|
|||
## Включения кода с диапазонами строк { #code-includes-with-line-ranges } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] *} |
|||
|
|||
|
|||
## Включения кода с диапазонами строк и подсветкой { #code-includes-with-line-ranges-and-highlighting } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial015_an_py310.py ln[10:15] hl[12:14] *} |
|||
|
|||
|
|||
## Включения кода с заголовком { #code-includes-with-title } |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/routers/users.py hl[1,3] title["app/routers/users.py"] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
## Включения кода с неизвестными атрибутами { #code-includes-with-unknown-attributes } |
|||
|
|||
{* ../../docs_src/python_types/tutorial001_py39.py unknown[123] *} |
|||
|
|||
## Ещё включения кода для тестирования исправления { #some-more-code-includes-to-test-fixing } |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[19:21] *} |
|||
|
|||
{* ../../docs_src/bigger_applications/app_an_py39/internal/admin.py hl[3] title["app/internal/admin.py"] *} |
|||
|
|||
{* ../../docs_src/dependencies/tutorial013_an_py310.py ln[30:38] hl[31:33] *} |
|||
|
|||
# Ссылки { #links } |
|||
|
|||
## Ссылки в стиле Markdown { #markdown-style-links } |
|||
|
|||
Это [Markdown-ссылка](https://example.com) на внешний сайт. |
|||
|
|||
Это ссылка с атрибутами: [**FastAPI** генераторы проектов](project-generation.md){.internal-link target=_blank} |
|||
|
|||
Это ссылка на основной сайт FastAPI: [FastAPI](https://fastapi.tiangolo.com/lang) — инструмент должен добавить код языка в URL. |
|||
|
|||
Это ссылка на одну из страниц на сайте FastAPI: [How to](https://fastapi.tiangolo.com/lang/how-to/) — инструмент должен добавить код языка в URL. |
|||
|
|||
Ссылка для тестирования неправильного атрибута: [**FastAPI** генераторы проектов](project-generation.md){.internal-link} - инструмент должен исправить атрибут. |
|||
|
|||
Ссылка с заголовком: [Пример](https://example.com "Сайт для примера") - URL будет исправлен инструментом, заголовок сохранится. |
|||
|
|||
### Markdown ссылки на статические ресурсы { #markdown-link-to-static-assets } |
|||
|
|||
Это ссылки на статические ресурсы: |
|||
|
|||
* [FastAPI Logo](https://fastapi.tiangolo.com/img/fastapi-logo.png) |
|||
* [FastAPI CSS](https://fastapi.tiangolo.com/css/fastapi.css) |
|||
* [FastAPI JS](https://fastapi.tiangolo.com/js/fastapi.js) |
|||
|
|||
Инструмент НЕ должен добавлять код языка в их URL. |
|||
|
|||
## Ссылки в стиле HTML { #html-style-links } |
|||
|
|||
Это <a href="https://example.com" target="_blank" class="external-link">HTML-ссылка</a> на внешний сайт. |
|||
|
|||
Это <a href="https://fastapi.tiangolo.com/lang">ссылка на основной сайт FastAPI</a> — инструмент должен добавить код языка в URL. |
|||
|
|||
Это <a href="https://fastapi.tiangolo.com/lang/how-to/">ссылка на одну из страниц на сайте FastAPI</a> — инструмент должен добавить код языка в URL. |
|||
|
|||
Ссылка для тестирования неправильного атрибута: <a href="project-generation.md" class="internal-link">**FastAPI** генераторы проектов</a> - инструмент должен исправить атрибут. |
|||
|
|||
### HTML ссылки на статические ресурсы { #html-links-to-static-assets } |
|||
|
|||
Это ссылки на статические ресурсы: |
|||
|
|||
* <a href="https://fastapi.tiangolo.com/img/fastapi-logo.png">FastAPI Logo</a> |
|||
* <a href="https://fastapi.tiangolo.com/css/fastapi.css">FastAPI CSS</a> |
|||
* <a href="https://fastapi.tiangolo.com/js/fastapi.js">FastAPI JS</a> |
|||
|
|||
Инструмент НЕ должен добавлять код языка в их URL. |
|||
|
|||
# Заголовок (с HTML ссылкой на <a href="https://tiangolo.com">tiangolo.com</a>) { #header-with-html-link-to-tiangolo-com } |
|||
|
|||
#Не заголовок |
|||
|
|||
```Python |
|||
# Также не заголовок |
|||
``` |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,30 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_complex_doc/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc.md")], |
|||
indirect=True, |
|||
) |
|||
def test_fix(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 0, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = (data_path / "translated_doc_expected.md").read_text("utf-8") |
|||
assert fixed_content == expected_content |
|||
|
|||
assert "Fixing multiline code blocks in" in result.output |
|||
assert "Fixing markdown links in" in result.output |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Some more text |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Even more text |
|||
|
|||
# Header 4 { #header-4 } |
|||
|
|||
A bit more text |
|||
|
|||
#Not a header |
|||
|
|||
Final portion of text |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text |
|||
|
|||
# Header 2 { #header-2 } |
|||
|
|||
Some more text |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Even more text |
|||
|
|||
# Header 4 { #header-4 } |
|||
|
|||
A bit more text |
|||
|
|||
#Not a header |
|||
|
|||
Final portion of text |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Some more text |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Even more text |
|||
|
|||
## Header 4 { #header-4 } |
|||
|
|||
A bit more text |
|||
|
|||
#Not a header |
|||
|
|||
Final portion of text |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Some more text |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Even more text |
|||
|
|||
# Header 4 { #header-4 } |
|||
|
|||
A bit more text |
|||
|
|||
# Extra header |
|||
|
|||
Final portion of text |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Some more text |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Even more text |
|||
|
|||
Header 4 is missing |
|||
|
|||
A bit more text |
|||
|
|||
#Not a header |
|||
|
|||
Final portion of text |
|||
@ -0,0 +1,60 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_header_permalinks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_level_mismatch_1.md")], |
|||
indirect=True, |
|||
) |
|||
def test_level_mismatch_1(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path( |
|||
f"{data_path}/translated_doc_level_mismatch_1.md" |
|||
).read_text("utf-8") |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Header levels do not match between document and original document" |
|||
" (found #, expected ##) for header №2 in line 5" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_level_mismatch_2.md")], |
|||
indirect=True, |
|||
) |
|||
def test_level_mismatch_2(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path( |
|||
f"{data_path}/translated_doc_level_mismatch_2.md" |
|||
).read_text("utf-8") |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Header levels do not match between document and original document" |
|||
" (found ##, expected #) for header №4 in line 13" |
|||
) in result.output |
|||
@ -0,0 +1,60 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_header_permalinks/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of headers with permalinks does not match the number " |
|||
"in the original document (5 vs 4)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1 |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of headers with permalinks does not match the number " |
|||
"in the original document (3 vs 4)" |
|||
) in result.output |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text with a link to <a href="https://fastapi.tiangolo.com">FastAPI</a>. |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Two links here: <a href="https://fastapi.tiangolo.com/how-to/">How to</a> and <a href="project-generation.md" class="internal-link" target="_blank">Project Generators</a>. |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Another link: <a href="project-generation.md" class="internal-link" target="_blank" title="Link title">**FastAPI** Project Generators</a> with title. |
|||
|
|||
# Header 4 { #header-4 } |
|||
|
|||
Link to anchor: <a href="#header-2">Header 2</a> |
|||
|
|||
# Header with <a href="http://example.com">link</a> { #header-with-link } |
|||
|
|||
Some text |
|||
@ -0,0 +1,21 @@ |
|||
# Заголовок 1 { #header-1 } |
|||
|
|||
Немного текста со ссылкой на <a href="https://fastapi.tiangolo.com">FastAPI</a>. |
|||
|
|||
## Заголовок 2 { #header-2 } |
|||
|
|||
Две ссылки здесь: <a href="https://fastapi.tiangolo.com/how-to/">How to</a> и <a href="project-generation.md" class="internal-link" target="_blank">Project Generators</a>. |
|||
|
|||
### Заголовок 3 { #header-3 } |
|||
|
|||
Ещё ссылка: <a href="project-generation.md" class="internal-link" target="_blank" title="Тайтл">**FastAPI** Генераторы Проектов</a> с тайтлом. |
|||
|
|||
И ещё одна <a href="https://github.com">экстра ссылка</a>. |
|||
|
|||
# Заголовок 4 { #header-4 } |
|||
|
|||
Ссылка на якорь: <a href="#header-2">Заголовок 2</a> |
|||
|
|||
# Заголовок со <a href="http://example.com">ссылкой</a> { #header-with-link } |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,19 @@ |
|||
# Заголовок 1 { #header-1 } |
|||
|
|||
Немного текста со ссылкой на <a href="https://fastapi.tiangolo.com">FastAPI</a>. |
|||
|
|||
## Заголовок 2 { #header-2 } |
|||
|
|||
Две ссылки здесь: <a href="https://fastapi.tiangolo.com/how-to/">How to</a> и <a href="project-generation.md" class="internal-link" target="_blank">Project Generators</a>. |
|||
|
|||
### Заголовок 3 { #header-3 } |
|||
|
|||
Ещё ссылка: <a href="project-generation.md" class="internal-link" target="_blank" title="Тайтл">**FastAPI** Генераторы Проектов</a> с тайтлом. |
|||
|
|||
# Заголовок 4 { #header-4 } |
|||
|
|||
Ссылка на якорь: <a href="#header-2">Заголовок 2</a> |
|||
|
|||
# Заголовок с потерянной ссылкой { #header-with-link } |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,58 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path("scripts/tests/test_translation_fixer/test_html_links/data").absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of HTML links does not match the number " |
|||
"in the original document (7 vs 6)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
# assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of HTML links does not match the number " |
|||
"in the original document (5 vs 6)" |
|||
) in result.output |
|||
@ -0,0 +1,19 @@ |
|||
# Header 1 { #header-1 } |
|||
|
|||
Some text with a link to [FastAPI](https://fastapi.tiangolo.com). |
|||
|
|||
## Header 2 { #header-2 } |
|||
|
|||
Two links here: [How to](https://fastapi.tiangolo.com/how-to/) and [Project Generators](project-generation.md){.internal-link target=_blank}. |
|||
|
|||
### Header 3 { #header-3 } |
|||
|
|||
Another link: [**FastAPI** Project Generators](project-generation.md "Link title"){.internal-link target=_blank} with title. |
|||
|
|||
# Header 4 { #header-4 } |
|||
|
|||
Link to anchor: [Header 2](#header-2) |
|||
|
|||
# Header with [link](http://example.com) { #header-with-link } |
|||
|
|||
Some text |
|||
@ -0,0 +1,19 @@ |
|||
# Заголовок 1 { #header-1 } |
|||
|
|||
Немного текста со ссылкой на [FastAPI](https://fastapi.tiangolo.com). |
|||
|
|||
## Заголовок 2 { #header-2 } |
|||
|
|||
Две ссылки здесь: [How to](https://fastapi.tiangolo.com/how-to/) и [Project Generators](project-generation.md){.internal-link target=_blank}. |
|||
|
|||
### Заголовок 3 { #header-3 } |
|||
|
|||
Ещё ссылка: [**FastAPI** Генераторы Проектов](project-generation.md "Тайтл"){.internal-link target=_blank} с тайтлом. |
|||
|
|||
# Заголовок 4 { #header-4 } |
|||
|
|||
Ссылка на якорь: [Заголовок 2](#header-2) |
|||
|
|||
# Заголовок со [ссылкой](http://example.com) { #header-with-link } |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,21 @@ |
|||
# Заголовок 1 { #header-1 } |
|||
|
|||
Немного текста со ссылкой на [FastAPI](https://fastapi.tiangolo.com). |
|||
|
|||
## Заголовок 2 { #header-2 } |
|||
|
|||
Две ссылки здесь: [How to](https://fastapi.tiangolo.com/how-to/) и [Project Generators](project-generation.md){.internal-link target=_blank}. |
|||
|
|||
### Заголовок 3 { #header-3 } |
|||
|
|||
Ещё ссылка: [**FastAPI** Генераторы Проектов](project-generation.md "Тайтл"){.internal-link target=_blank} с тайтлом. |
|||
|
|||
И ещё одна [экстра ссылка](https://github.com). |
|||
|
|||
# Заголовок 4 { #header-4 } |
|||
|
|||
Ссылка на якорь: [Заголовок 2](#header-2) |
|||
|
|||
# Заголовок со [ссылкой](http://example.com) { #header-with-link } |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,19 @@ |
|||
# Заголовок 1 { #header-1 } |
|||
|
|||
Немного текста со ссылкой на [FastAPI](https://fastapi.tiangolo.com). |
|||
|
|||
## Заголовок 2 { #header-2 } |
|||
|
|||
Две ссылки здесь: [How to](https://fastapi.tiangolo.com/how-to/) и [Project Generators](project-generation.md){.internal-link target=_blank}. |
|||
|
|||
### Заголовок 3 { #header-3 } |
|||
|
|||
Ещё ссылка: [**FastAPI** Генераторы Проектов](project-generation.md "Тайтл"){.internal-link target=_blank} с тайтлом. |
|||
|
|||
# Заголовок 4 { #header-4 } |
|||
|
|||
Ссылка на якорь: [Заголовок 2](#header-2) |
|||
|
|||
# Заголовок с потерянной ссылкой { #header-with-link } |
|||
|
|||
Немного текста |
|||
@ -0,0 +1,60 @@ |
|||
from pathlib import Path |
|||
|
|||
import pytest |
|||
from typer.testing import CliRunner |
|||
|
|||
from scripts.translation_fixer import cli |
|||
|
|||
data_path = Path( |
|||
"scripts/tests/test_translation_fixer/test_markdown_links/data" |
|||
).absolute() |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_gt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_gt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_gt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of markdown links does not match the number " |
|||
"in the original document (7 vs 6)" |
|||
) in result.output |
|||
|
|||
|
|||
@pytest.mark.parametrize( |
|||
"copy_test_files", |
|||
[(f"{data_path}/en_doc.md", f"{data_path}/translated_doc_number_lt.md")], |
|||
indirect=True, |
|||
) |
|||
def test_lt(runner: CliRunner, root_dir: Path, copy_test_files): |
|||
result = runner.invoke( |
|||
cli, |
|||
["fix-pages", "docs/lang/docs/doc.md"], |
|||
) |
|||
# assert result.exit_code == 1, result.output |
|||
|
|||
fixed_content = (root_dir / "docs" / "lang" / "docs" / "doc.md").read_text("utf-8") |
|||
expected_content = Path(f"{data_path}/translated_doc_number_lt.md").read_text( |
|||
"utf-8" |
|||
) |
|||
|
|||
assert fixed_content == expected_content # Translated doc remains unchanged |
|||
assert "Error processing docs/lang/docs/doc.md" in result.output |
|||
assert ( |
|||
"Number of markdown links does not match the number " |
|||
"in the original document (5 vs 6)" |
|||
) in result.output |
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue