{"id":15495936,"url":"https://github.com/omenapps/polyglotmarkdown","last_synced_at":"2026-03-14T20:37:29.375Z","repository":{"id":254799644,"uuid":"847561257","full_name":"OmenApps/PolyglotMarkdown","owner":"OmenApps","description":"A versatile Markdown extension designed to manage and display multilingual content within a single document, offering powerful features like language-specific content inclusion, multi-language metadata support, and version control for a global audience.","archived":false,"fork":false,"pushed_at":"2024-09-06T04:43:52.000Z","size":39,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-15T06:48:52.934Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OmenApps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-26T05:26:46.000Z","updated_at":"2025-02-07T14:33:17.000Z","dependencies_parsed_at":"2024-08-29T05:23:03.909Z","dependency_job_id":"bec83d23-75d7-42e7-b2b1-27f9c3a13917","html_url":"https://github.com/OmenApps/PolyglotMarkdown","commit_stats":null,"previous_names":["omenapps/polyglotmarkdown"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2FPolyglotMarkdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2FPolyglotMarkdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2FPolyglotMarkdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OmenApps%2FPolyglotMarkdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OmenApps","download_url":"https://codeload.github.com/OmenApps/PolyglotMarkdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249023707,"owners_count":21199958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T08:20:38.344Z","updated_at":"2025-10-10T07:33:29.167Z","avatar_url":"https://github.com/OmenApps.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# PolyglotMarkdown\n\nA versatile Markdown extension designed to manage and display multilingual content within a single document, offering powerful features like language-specific content inclusion, multi-language metadata support, and version control for a global audience.\n\nThis project is a *Work in Progress*\n\n## Table of contents\n\n- [PolyglotMarkdown](#polyglotmarkdown)\n  - [Table of contents](#table-of-contents)\n  - [Overview](#overview)\n  - [Why Would I Use This Instead of Separate Files for Each Language?](#why-would-i-use-this-instead-of-separate-files-for-each-language)\n  - [Key Features](#key-features)\n    - [1. Metadata Section](#1-metadata-section)\n      - [Fallback Language Support](#fallback-language-support)\n    - [2. Portion Marking](#2-portion-marking)\n    - [3. Comments and Annotations](#3-comments-and-annotations)\n    - [4. Content Versioning](#4-content-versioning)\n    - [5. Transclusion (Including External Content)](#5-transclusion-including-external-content)\n    - [6. Inter-document Links with Language Awareness](#6-inter-document-links-with-language-awareness)\n    - [7. Multi-language Indexing and Search](#7-multi-language-indexing-and-search)\n  - [Using the PolyglotParser Python Class](#using-the-polyglotparser-python-class)\n    - [Initialization](#initialization)\n    - [Parsing Metadata](#parsing-metadata)\n    - [Parsing Metadata by Language](#parsing-metadata-by-language)\n    - [Parsing Content](#parsing-content)\n    - [Handling Fallback Language](#handling-fallback-language)\n    - [Handling Versioning](#handling-versioning)\n    - [Handling Transclusion](#handling-transclusion)\n    - [Example Usage](#example-usage)\n      - [Example Document Content](#example-document-content)\n      - [External Files](#external-files)\n      - [Parsing and Handling the Document](#parsing-and-handling-the-document)\n      - [Expected Output](#expected-output)\n    - [Using the PolyglotParser Methods](#using-the-polyglotparser-methods)\n      - [Example PolyglotMarkdown Document](#example-polyglotmarkdown-document)\n      - [Initializing the Parser](#initializing-the-parser)\n      - [Parsing Metadata](#parsing-metadata-1)\n      - [Parsing Metadata by Language](#parsing-metadata-by-language-1)\n      - [Listing Available Languages](#listing-available-languages)\n      - [Parsing Content by Language](#parsing-content-by-language)\n  - [Using the PolyglotBuilder Python Class](#using-the-polyglotbuilder-python-class)\n    - [Initialization](#initialization-1)\n  - [In Closing](#in-closing)\n\n\u003c!-- Created with https://luciopaiva.com/markdown-toc/ --\u003e\n\n## Overview\n\nThis document introduces the *PolyglotMarkdown* format and the `PolyglotParser` Python class, which can parse and process *PolyglotMarkdown* documents. A goal of this project is to provide parsers in other programming languages in the near future.\n\nThe *PolyglotMarkdown* format is an extension of Markdown designed to allow authors to create documents that can be read in multiple languages. This format is designed to be simple to use, easy to read and write, and compatible with existing Markdown tools. It is also flexible enough to handle complex scenarios such as dynamic content inclusion, versioning, transclusion, and language-aware internal links.\n\nThe *PolyglotMarkdown* format is ideal for creating documents that need to be accessible in multiple languages, such as documentation, knowledge bases, and other multilingual content.\n\n## Why Would I Use This Instead of Separate Files for Each Language?\n\nImagine you have 100 articles in your knowledge base, and right now you’re managing them in two languages. With separate Markdown files per language, that’s already 200 files to manage! As your business grows and you start adding more languages — 5 or even 10 — those 200 files will balloon into 500 or 1000. Painful!\n\nBut PolyglotMarkdown might be just what you're looking for. Instead of trying to keep every language version of your articles consistently worded and consistently formatted across a bunch of files, PolyglotMarkdown lets you manage everything in one tidy package. Want to add a new section to an article? You can do it in one place, and it’s there for every language. Need to delete something? One and done. No need to open a dozen files just to make the same small change for all the languages you support.\n\nOne of the significant advantages of PolyglotMarkdown is the ability to manage partially translated content. On many multilingual websites, some content of lesser value or interest is often left untranslated \"for later\" and may or may not get translated in the end. If you use a multi-file approach, you would have to copy and paste these sections across different language files. However, with PolyglotMarkdown's [fallback mechanism](#handling-fallback-language), you can maintain such sections in the fallback language, ensuring that they are still available to readers even if they aren't translated.\n\nThis approach is not just beneficial for content that might be translated in the future. There are sections of documents that often do not require translation at all, such as code snippets or mathematical formulas. With PolyglotMarkdown, these can remain in the fallback language, or be included as-is, without needing redundant copies across multiple files.\n\nBut PolyglotMarkdown isn’t all-or-nothing. If you already have separate files for each language and that works for you, great! You can combine them into a PolyglotMarkdown document using [transclusion](#5-transclusion-including-external-content) and enjoy the benefits without tossing your existing workflow out the window. It’s flexible.\n\nSo, if you’re looking to keep your sanity as your content grows and the number of languages you support increases, PolyglotMarkdown is worth considering. It’s like having one file to rule them all, making your work smoother, faster, and less stressful. And who doesn’t want that?\n\n## Key Features\n\nThe *PolyglotMarkdown* format is simply an extension of the standard Markdown format, with additional features to support multilingual content. Here are some key features of the *PolyglotMarkdown* format:\n\n### 1. Metadata Section\n\nThe document begins with a metadata block marked by `---` at the beginning and end. This section is used to define key information about the document, such as the title, author, date, and other relevant metadata. The metadata can be defined in multiple languages, allowing for language-specific metadata. Currently, the only top-level metadata keys specified in `PolyglotMarkdown` are [`fallback_lang`](#fallback-language-support) and [`versions`](#4-content-versioning). Any other metadata can be defined as needed, with each language-specific value nested under the appropriate key.\n\n**Example:**\n\n```markdown\n---\ntitle:\n  en: \"The Great Adventure\"\n  es: \"La Gran Aventura\"\nauthor:\n  en: \"John Doe\"\n  es: \"Juan Pérez\"\ndate:\n  en: \"08-25-2024\"\n  es: \"25-08-2024\"\nfallback_lang: \"en\"\nversions:\n  en: \"1.0\"\n  es: \"1.1\"\n---\n```\n\n#### Fallback Language Support\n\nIf content in the requested language is not available, you can specify a fallback language using the `fallback_lang` field in the metadata. This ensures that the reader can still access the content, even if it's not available in their preferred language.\n\n**Example:**\n\n```markdown\n---\ntitle:\n  en: \"The Great Adventure\"\n  es: \"La Gran Aventura\"\nfallback_lang: \"en\"\n---\n```\n\n### 2. Portion Marking\n\nThe content section of the document can be portion-marked by language in two ways:\n\n1. **Per Line:**\n   You can mark individual lines with a language code using the syntax `:[lang-code]:`. This allows for precise control over which language is displayed for each piece of content.\n\n   **Example:**\n\n   ```markdown\n   :[en]: This is the first paragraph in English.\n   :[es]: Este es el primer párrafo en español.\n   ```\n\n2. **Per Paragraph or Section:**\n   Alternatively, you can group entire sections of content by language. Each block of content is marked with a specific language delimiter using the syntax `:[lang:lang-code]:`.\n\n   **Example:**\n\n   ```markdown\n   :[lang:en]:\n   This is a section in English.\n\n   Here is another paragraph in English.\n\n   :[lang:es]:\n   Esta es una sección en español.\n\n   Aquí hay otro párrafo en español.\n   ```\n\n### 3. Comments and Annotations\n\nThe *PolyglotMarkdown* format allows for language-specific comments or annotations. These can be used by authors or translators to provide context or notes within the document.\n\n**Syntax:**\nUse HTML-style comments with a language tag.\n\n**Example:**\n\n```markdown\n\u003c!-- Comment :[en]: This section needs review --\u003e\n:[en]: This is the content in English.\n\n\u003c!-- Comment :[es]: Esta sección necesita revisión --\u003e\n:[es]: Este es el contenido en español.\n```\n\n### 4. Content Versioning\n\n*PolyglotMarkdown* supports versioning within the document, allowing authors to maintain different versions of content for different languages or editions. Versioning is defined in the metadata and referenced within the content using the `:[version \"x.x\"]:` syntax.\n\n**Example:**\n\n```markdown\n---\nversions:\n  en: \"1.1\"\n  es: \"1.0\"\n---\n\n:[version \"1.0\"]:\n:[lang:en]: This is version 1.0 in English. It will not be shown, as the version is 1.1.\n:[lang:es]: Esta es la versión 1.0 en español.\n\n:[version \"1.1\"]:\n:[lang:en]: This is version 1.1 in English.\n:[lang:es]: Esta es la versión 1.1 en español. No se mostrará porque la versión es 1.0.\n```\n\n### 5. Transclusion (Including External Content)\n\n*PolyglotMarkdown* supports transclusion, which allows you to include content from external files. This is useful for large projects where content is maintained in different places. You can include an entire file, ignoring language-specific sections, or include content for a specific language.\n\nTo include all content from an external file:\n\n**Syntax:**\n`:[include \"file.md\"]:`\n\nTo include only relevant content for the specified language in the final document (in the order such content appears in the source file):\n\n**Syntax:**\n`:[include \"file.md\" lang:code]:`\n\n**Example:**\n\n```markdown\n:[include \"bike_article.md\" lang:en]:\n```\n\n### 6. Inter-document Links with Language Awareness\n\n\u003e **Note:** This feature is experimental and may require additional processing by the consuming application.\n\nCreate links to other documents that automatically resolve to the appropriate language version if it exists. This ensures that internal links work correctly regardless of the language being viewed.\n\n**Syntax:**\nUse `:[link \"document.md\" lang:code]:` to create language-aware links.\n\n**Example:**\n\n```markdown\n:[en]: See the [related document](:[link \"related_doc.md\" lang:en]:).\n:[es]: Consulte el [documento relacionado](:[link \"related_doc.md\" lang:es]:).\n```\n\n### 7. Multi-language Indexing and Search\n\nThe *PolyglotMarkdown* format is designed to support multi-language indexing and search capabilities. This allows users to search within the document in their preferred language. While the file format itself supports this, the implementation would typically be handled by the application consuming the *PolyglotMarkdown* files.\n\n## Using the PolyglotParser Python Class\n\nThe `PolyglotParser` class is designed to parse *PolyglotMarkdown* texts and files, allowing you to extract and manipulate the content based on language, version, and other parameters.\n\n### Initialization\n\nTo use the parser, instantiate it with the text of a *PolyglotMarkdown* document.\n\n```python\nfrom polyglot_parser import PolyglotParser\n\nparser = PolyglotParser(markdown_string=content)\n```\n\nAlternately, if you have a file, you can read the content and pass the file path as a string:\n\n```python\nfrom polyglot_parser import PolyglotParser\n\nparser = PolyglotParser(markdown_file=\"document.md\")\n```\n\nOr as a `Path` object:\n\n```python\nfrom pathlib import Path\nfrom polyglot_parser import PolyglotParser\n\nfile_path = Path(\"document.md\")\nparser = PolyglotParser(markdown_file=file_path)\n```\n\n### Parsing Metadata\n\nThe `parse_metadata()` method extracts the metadata from the document and returns it as a dictionary with language-specific values nested under their respective keys.\n\n```python\nmetadata = parser.parse_metadata()\n```\n\nExample output:\n\n```json\n{\n  \"title\": {\"en\": \"The Great Adventure\", \"es\": \"La Gran Aventura\"},\n  \"author\": {\"en\": \"John Doe\", \"es\": \"Juan Pérez\"},\n  \"date\": \"2024-08-25\",\n  \"fallback_lang\": \"en\",\n  \"versions\": {\"en\": \"1.0\", \"es\": \"1.1\"}\n}\n```\n\n### Parsing Metadata by Language\n\nThe `parse_metadata_by_language()` method restructures the metadata, returning a dictionary organized by language.\n\n```python\nmetadata_by_language = parser.parse_metadata_by_language()\n```\n\nExample output:\n```json\n{\n  \"en\": {\"title\": \"The Great Adventure\", \"author\": \"John Doe\", \"date\": \"2024-08-25\", \"fallback_lang\": \"en\", \"versions\": \"1.0\"},\n  \"es\": {\"title\": \"La Gran Aventura\", \"author\": \"Juan Pérez\", \"date\": \"2024-08-25\", \"fallback_lang\": \"en\", \"versions\": \"1.1\"}\n}\n```\n\n### Parsing Content\n\nThe `parse_content()` method parses the content, separating it into language-specific sections and returning a dictionary where the keys are language codes and the values are the respective content.\n\n```python\ncontent = parser.parse_content()\n```\n\n### Handling Fallback Language\n\nIf content in the requested language is missing, the parser will automatically use the fallback language specified in the metadata.\n\n```python\noutput = parser.convert_to_markdown(lang='es')  # Will fallback to 'en' if 'es' content is missing\n```\n\n### Handling Versioning\n\nThe `handle_versioning(version=\"x.x\")` method allows you to filter content based on a specific version.\n\n```python\nparser.handle_versioning(version=\"1.1\")\n```\n\n### Handling Transclusion\n\nThe `handle_transclusion()` method processes `:[include ...]:` tags, replacing them with the content of the specified files.\n\n```python\nparser.handle_transclusion()\n```\n\n### Example Usage\n\nLet's consider a more comprehensive example that includes content in English, Spanish, and French, multiple sections, metadata, inter-document links, and external file transclusions.\n\n#### Example Document Content\n\n```python\ncontent = \"\"\"\n---\ntitle:\n  en: \"The Great Adventure\"\n  es: \"La Gran Aventura\"\n  fr: \"La Grande Aventure\"\nauthor:\n  en: \"John Doe\"\n  es: \"Juan Pérez\"\n  fr: \"Jean Dupont\"\nregion:\n  en: \"United States of America\"\n  es: \"Centroamérica\"\n  fr: \"Europe\"\ndate: \"2024-09-05\"\nfallback_lang: \"en\"\nversions:\n  en: \"1.0\"\n  es: \"1.1\"\n  fr: \"1.1\"\n---\n\n:[lang:en]:\n# Introduction\n\nWelcome to **The Great Adventure**. This document will guide you through the basics of using PolyglotMarkdown.\n\n:[lang:es]:\n# Introducción\n\nBienvenidos a **La Gran Aventura**. Este documento le guiará a través de los conceptos básicos del uso de PolyglotMarkdown.\n\n:[lang:fr]:\n# Introduction\n\nBienvenue dans **La Grande Aventure**. Ce document vous guidera à travers les bases de l'utilisation de PolyglotMarkdown.\n\n:[lang:en]:\n# First Section\n\nHere is the first section with some sample text in English.\n\n# Versioned Content\n\n:[lang:es]:\n# Primera Sección\n\nAquí está la primera sección con un texto de ejemplo en español.\n\n# Contenido Versionado\n\n:[lang:fr]:\n# Première Section\n\nVoici la première section avec un exemple de texte en français.\n\n# Contenu Versionné\n\n:[version \"1.0\"]:\n:[en]: - This English content is for version 1.0.\n\n:[version \"1.1\"]:\n:[en]: - This English version 1.1 bullet-point won't be used!\n:[es]: - Este contenido en español es para la versión 1.1.\n:[fr]: - Ce contenu en français est pour la version 1.1.\n\n:[lang:en]:\n# Inter-document Links\n\nFor more details, check out the [Advanced Features](:[link \"advanced_features.md\" lang:en]:) document, specifically section [Advanced Feature 1](:[link \"advanced_features.md#advanced-feature-1\" lang:en]:).\n\n:[lang:es]:\n# Enlaces entre Documentos\n\nPara más detalles, consulte el documento [Funciones avanzadas](:[link \"advanced_features.md\" lang:es]:), específicamente la sección [Función Avanzada 1](:[link \"advanced_features.md#función-avanzada-1\" lang:es]:).\n\n:[lang:fr]:\n# Liens Inter-documents\n\nPour plus de détails, consultez le document [Fonctionnalités avancées](:[link \"advanced_features.md\" lang:fr]:), en particulier la section [Fonctionnalité Avancée 1](:[link \"advanced_features.md#fonctionnalité-avancée-1\" lang:fr]:).\n\n:[lang:en]:\n# External Content\n\nHere is some included English content from an external file with a single language:\n:[include \"extra_content_en.md\"]:\n\nThis content is also from an external file, but the file includes content for multiple languages:\n:[include \"external_file.md\" lang:en]:\n\n:[lang:es]:\n# Contenido Externo\n\nA continuación se incluye contenido en español desde un archivo externo con un solo idioma:\n:[include \"extra_content_es.md\"]:\n\nEste contenido también proviene de un archivo externo, pero el archivo incluye contenido para varios idiomas:\n:[include \"external_file.md\" lang:es]:\n\n:[lang:fr]:\n# Contenu Externe\n\nVoici quelques contenus français inclus à partir d’un fichier externe avec une seule langue:\n:[include \"extra_content_fr.md\"]:\n\nCe contenu provient également d'un fichier externe, mais le fichier inclut du contenu pour plusieurs langues:\n:[include \"external_file.md\" lang:fr]:\n\n:[lang:en]:\n# Conclusion\n\nThank you for reading **The Great Adventure**. We hope this helps you understand PolyglotMarkdown.\n\n:[lang:es]:\n# Conclusión\n\nGracias por leer **La Gran Aventura**. Esperamos que esto le ayude a comprender PolyglotMarkdown.\n\n:[lang:fr]:\n# Conclusion\n\nMerci d'avoir lu **La Grande Aventure**. Nous espérons que cela vous aidera à comprendre PolyglotMarkdown.\n\"\"\"\n```\n\n#### External Files\n\n**extra_content_en.md:**\n\n```markdown\nThis is additional content in English, included from an external file.\n```\n\n**extra_content_es.md:**\n\n```markdown\nEste es contenido adicional en español, incluido desde un archivo externo.\n```\n\n**extra_content_fr.md:**\n\n```markdown\nVoici du contenu supplémentaire en français, inclus à partir d'un fichier externe.\n```\n\n**external_file.md:**\n\n```markdown\n:[lang:en]:\nThis content...\n\n... is included from an external English file.\n\n:[lang:es]:\nEste contenido...\n\n... se incluye desde un archivo externo en español.\n\n:[lang:fr]:\nCe contenu...\n\n... est inclus à partir d'un fichier externe en français.\n\n:[es]: Quiero una manzana.\n\n:[en]: I want an apple.\n\n:[fr]: Je veux une pomme.\n```\n\n**advanced_features.md:**\n\n```markdown\n:[lang:en]:\nThis document contains advanced features.\n\n# Advanced Feature 1\n\nThis is the first advanced feature.\n\n:[lang:es]:\nEste documento contiene funciones avanzadas.\n\n# Función Avanzada 1\n\nEsta es la primera función avanzada.\n\n:[lang:fr]:\nCe document contient des fonctionnalités avancées.\n\n# Fonctionnalité Avancée 1\n\nCeci est la première fonctionnalité avancée.\n```\n\n#### Parsing and Handling the Document\n\nHere’s how you can use the `PolyglotParser` to handle this document:\n\n```python\n# Create the parser instance\nparser = PolyglotParser(markdown_string=content)\n\n# Parse the metadata\nparser.parse_metadata()\n\n# Parse the content\nparser.parse_content()\n\n# Handle versioning (we'll work with version 1.1 in this example)\nparser.handle_versioning(version=\"1.1\")\n\n# Handle transclusion (including content from external files)\nparser.handle_transclusion()\n\n# Convert the content to markdown for a specific language\nenglish_output = parser.convert_to_markdown(lang='en')\nspanish_output = parser.convert_to_markdown(lang='es')\nfrench_output = parser.convert_to_markdown(lang='fr')\n\n# Print the outputs for each language\nprint(\"English Output:\\n\", english_output)\nprint(\"\\nSpanish Output:\\n\", spanish_output)\nprint(\"\\nFrench Output:\\n\", french_output)\n```\n\n#### Expected Output\n\nGiven the document content and the external files, the expected output for each language is as follows:\n\n**English Output:**\n\n```markdown\n# Introduction\n\nWelcome to **The Great Adventure**. This document will guide you through the basics of using PolyglotMarkdown.\n\n# First Section\n\nHere is the first section with some sample text in English.\n\n# Versioned Content\n\n- This English content is for version 1.0.\n\n# Inter-document Links\n\nFor more details, check out the [Advanced Features](advanced_features.md) document, specifically section [Advanced Feature 1](advanced_features.md#advanced-feature-1).\n\n# External Content\n\nHere is some included English content from an external file with a single language:\nThis is additional content in English, included from an external file.\n\nThis content is also from an external file, but the file includes content for multiple languages:\nThis content...\n\n... is included from an external English file.\n\nI want an apple.\n\n# Conclusion\n\nThank you for reading **The Great Adventure**. We hope this helps you understand PolyglotMarkdown.\n```\n\n**Spanish Output:**\n\n```markdown\n# Introducción\n\nBienvenidos a **La Gran Aventura**. Este documento le guiará a través de los conceptos básicos del uso de PolyglotMarkdown.\n\n# Primera Sección\n\nAquí está la primera sección con un texto de ejemplo en español.\n\n# Contenido Versionado\n\n- Este contenido en español es para la versión 1.1.\n\n# Enlaces entre Documentos\n\nPara más detalles, consulte el documento [Funciones avanzadas](advanced_features.md), específicamente la sección [Función Avanzada 1](advanced_features.md#función-avanzada-1).\n\n# Contenido Externo\n\nA continuación se incluye contenido en español desde un archivo externo con un solo idioma:\nEste es contenido adicional en español, incluido desde un archivo externo.\n\nEste contenido también proviene de un archivo externo, pero el archivo incluye contenido para varios idiomas:\nEste contenido...\n\n... se incluye desde un archivo externo en español.\n\nQuiero una manzana.\n\n# Conclusión\n\nGracias por leer **La Gran Aventura**. Esperamos que esto le ayude a comprender PolyglotMarkdown.\n```\n\n**French Output:**\n\n```markdown\n# Introduction\n\nBienvenue dans **La Grande Aventure**. Ce document vous guidera à travers les bases de l'utilisation de PolyglotMarkdown.\n\n# Première Section\n\nVoici la première section avec un exemple de texte en français.\n\n# Contenu Versionné\n\n- Ce contenu en français est pour la version 1.1.\n\n# Liens Inter-documents\n\nPour plus de détails, consultez le document [Fonctionnalités avancées](advanced_features.md), en particulier la section [Fonctionnalité Avancée 1](advanced_features.md#fonctionnalité-avancée-1).\n\n# Contenu Externe\n\nVoici quelques contenus français inclus à partir d’un fichier externe avec une seule langue:\nVoici du contenu supplémentaire en français, inclus à partir d'un fichier externe.\n\nCe contenu provient également d'un fichier externe, mais le fichier inclut du contenu pour plusieurs langues:\nCe contenu...\n\n... est inclus à partir d'un fichier externe en français.\n\nJe veux une pomme.\n\n# Conclusion\n\nMerci d'avoir lu **La Grande Aventure**. Nous espérons que cela vous aidera à comprendre PolyglotMarkdown.\n```\n\n### Using the PolyglotParser Methods\n\nHere, we demonstrate how to use various methods of the `PolyglotParser` Python class and the resulting output for each, using the example PolyglotMarkdown text provided below.\n\n#### Example PolyglotMarkdown Document\n\n```markdown\n---\ntitle:\n  en: \"The Great Adventure\"\n  es: \"La Gran Aventura\"\nauthor:\n  en: \"John Doe\"\n  es: \"Juan Pérez\"\ndate: \"2024-08-25\"\nfallback_lang: \"en\"\nversions:\n  en: \"1.0\"\n  es: \"1.1\"\n---\n\n# Introduction\n\n:[lang:en]:\nThis is the introduction in **English**.\n\n:[lang:es]:\nEsta es la introducción en **español**.\n\n:[lang:en]:\nThis is the More English content.\n\n:[lang:es]:\nEste es el contenido Más español.\n```\n\n#### Initializing the Parser\n\nTo begin, initialize the `PolyglotParser` with the markdown content.\n\n```python\nparser = PolyglotParser(markdown_string=text)\n```\n\n#### Parsing Metadata\n\nThe `parse_metadata()` method extracts the metadata from the document, including the title, author, date, fallback language, and versions.\n\n```python\nmetadata = parser.parse_metadata()\nprint(metadata)\n```\n\n**Expected Output:**\n\n```json\n{\n  \"title\": {\n    \"en\": \"The Great Adventure\",\n    \"es\": \"La Gran Aventura\"\n  },\n  \"author\": {\n    \"en\": \"John Doe\",\n    \"es\": \"Juan Pérez\"\n  },\n  \"date\": \"2024-08-25\",\n  \"fallback_lang\": \"en\",\n  \"versions\": {\n    \"en\": \"1.0\",\n    \"es\": \"1.1\"\n  }\n}\n```\n\n#### Parsing Metadata by Language\n\nThe `parse_metadata_by_language()` method organizes the metadata by language, providing a view where each language has its corresponding metadata.\n\n```python\nmetadata_by_language = parser.parse_metadata_by_language()\nprint(metadata_by_language)\n```\n\n**Expected Output:**\n\n```json\n{\n  \"en\": {\n    \"title\": \"The Great Adventure\",\n    \"author\": \"John Doe\",\n    \"date\": \"2024-08-25\",\n    \"fallback_lang\": \"en\",\n    \"versions\": \"1.0\"\n  },\n  \"es\": {\n    \"title\": \"La Gran Aventura\",\n    \"author\": \"Juan Pérez\",\n    \"date\": \"2024-08-25\",\n    \"fallback_lang\": \"en\",\n    \"versions\": \"1.1\"\n  }\n}\n```\n\n#### Listing Available Languages\n\nThe `list_languages()` method identifies all the languages available in the document.\n\n```python\nlanguages = parser.list_languages()\nprint(languages)\n```\n\n**Expected Output:**\n\n```python\n['es', 'en']\n```\n\n#### Parsing Content by Language\n\nThe `parse_content()` method parses the content, returning a dictionary where the keys are the language codes, and the values are the content in those respective languages.\n\n```python\ncontent = parser.parse_content()\nprint(content)\n```\n\n**Expected Output:**\n\n```json\n{\n  \"es\": \"Esta es la introducción en **español**.\\n\\nEste es el contenido Más español.\",\n  \"en\": \"This is the introduction in **English**.\\n\\nThis is the More English content.\"\n}\n```\n\nTo retrieve the content for only one language, falling back to `fallback_language` for any missing content, you can use the `parse_content()` method along with the `lang` parameter.\n\n```python\nenglish_content = parser.parse_content(lang='en')\nprint(english_content)\n```\n\nThese methods allow you to extract and manage multilingual content and metadata in PolyglotMarkdown texts and documents.\n\n## Using the PolyglotBuilder Python Class\n\n\u003e **Note:** This feature is planned for future development.\n\nThe `PolyglotBuilder` class is designed to create *PolyglotMarkdown* documents programmatically. This class provides methods to set metadata, add content in multiple languages, and handles versioning and transclusion.\n\n### Initialization\n\nTo use the builder, instantiate it with the desired metadata and content.\n\n```python\nfrom polyglot_builder import PolyglotBuilder\n\nbuilder = PolyglotBuilder()\n```\n\n## In Closing\n\n- The *PolyglotMarkdown* format provides a way to manage multilingual content in a single document or a set of documents. This format ensures that your content is accessible, maintainable, and easy to work with across multiple languages.\n- The `PolyglotParser` class offers a robust tool for parsing, processing, and converting *PolyglotMarkdown* documents, making it easy to integrate *PolyglotMarkdown* into your existing workflows and applications.\n- The `PolyglotBuilder` class, planned for future development, will provide a way to create *PolyglotMarkdown* documents programmatically, enabling you to generate multilingual content dynamically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fpolyglotmarkdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomenapps%2Fpolyglotmarkdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomenapps%2Fpolyglotmarkdown/lists"}