main.py

import csv
import json
import logging
import os
import re

import requests
import yaml

log = logging.getLogger("mkdocs.macros.translations")

# Friendly names for the locale codes we expect to encounter. Anything not
# listed here will fall back to its bare locale code as the display name.
LANGUAGE_NAMES = {
    "zh-CN": "Chinese, China",
    "zh-HK": "Chinese, Hong Kong",
    "zh-TW": "Chinese, Taiwan",
    "hr": "Croatian",
    "cs": "Czech",
    "nl": "Dutch",
    "fr": "French",
    "de": "German",
    "hu": "Hungarian",
    "id": "Indonesian",
    "it": "Italian",
    "ja": "Japanese",
    "ko": "Korean",
    "lv": "Latvian",
    "pl": "Polish",
    "pt": "Portuguese",
    "pt-BR": "Portuguese, Brazil",
    "en-GB": "English, United Kingdom",
    "es-ES": "Spanish, Spain",
    "fr-FR": "French, France",
    "ro": "Romanian",
    "ru": "Russian",
    "es": "Spanish",
    "tr": "Turkish",
    "uk": "Ukrainian",
    "vi": "Vietnamese",
}

# Module-level cache so each (repo, branch) is fetched at most once per build,
# even though several pages may reference the same repo.
_translations_cache: dict = {}

GITHUB_ORG = "BentoBoxWorld"
LOCALES_PATH = "src/main/resources/locales"
ENGLISH_FILE = "en-US.yml"


def _gh_session():
    s = requests.Session()
    s.headers.update({"Accept": "application/vnd.github+json"})
    token = os.environ.get("GITHUB_TOKEN")
    if token:
        s.headers["Authorization"] = f"token {token}"
    return s


def _flatten_yaml(data, prefix=""):
    """Flatten a nested YAML mapping into {dotted.key: leaf_value}."""
    out = {}
    if isinstance(data, dict):
        for k, v in data.items():
            key = f"{prefix}.{k}" if prefix else str(k)
            out.update(_flatten_yaml(v, key))
    elif isinstance(data, list):
        # Treat the whole list as a single leaf — translators usually
        # translate the list as a unit.
        out[prefix] = "\n".join(str(x) for x in data)
    else:
        out[prefix] = data
    return out


def _is_translated(value, english_value) -> bool:
    """A key counts as translated if it has a non-empty value."""
    if value is None:
        return False
    if isinstance(value, str) and not value.strip():
        return False
    return True


def _fetch_translation_status(repo: str, branch: str):
    """Return a list of dicts: {code, name, url, percent} for every locale
    file in the repo (excluding en-US.yml). On failure returns None."""
    cache_key = (repo, branch)
    if cache_key in _translations_cache:
        return _translations_cache[cache_key]

    session = _gh_session()
    api_url = (
        f"https://api.github.com/repos/{GITHUB_ORG}/{repo}/contents/"
        f"{LOCALES_PATH}?ref={branch}"
    )
    try:
        r = session.get(api_url, timeout=15)
        if r.status_code == 404:
            # The repo has no locales/ directory at all — distinct from a
            # transient failure so callers can render an accurate message.
            _translations_cache[cache_key] = "missing"
            return "missing"
        if r.status_code != 200:
            log.warning(
                "translations(%s): GitHub listing returned %s", repo, r.status_code
            )
            _translations_cache[cache_key] = None
            return None
        listing = r.json()
    except Exception as e:  # network errors, JSON errors, etc.
        log.warning("translations(%s): listing failed: %s", repo, e)
        _translations_cache[cache_key] = None
        return None

    yml_files = [
        item for item in listing
        if isinstance(item, dict)
        and item.get("type") == "file"
        and item.get("name", "").endswith(".yml")
    ]
    en_entry = next((f for f in yml_files if f["name"] == ENGLISH_FILE), None)
    if en_entry is None:
        log.warning("translations(%s): no %s in repo", repo, ENGLISH_FILE)
        _translations_cache[cache_key] = None
        return None

    def _raw(file_entry):
        url = file_entry.get("download_url")
        if not url:
            return None
        try:
            rr = session.get(url, timeout=15)
            if rr.status_code != 200:
                return None
            return rr.text
        except Exception:
            return None

    en_text = _raw(en_entry)
    if en_text is None:
        log.warning("translations(%s): could not fetch %s", repo, ENGLISH_FILE)
        _translations_cache[cache_key] = None
        return None

    try:
        en_flat = _flatten_yaml(yaml.safe_load(en_text) or {})
    except yaml.YAMLError as e:
        log.warning("translations(%s): could not parse %s: %s", repo, ENGLISH_FILE, e)
        _translations_cache[cache_key] = None
        return None

    total = len([k for k, v in en_flat.items() if v not in (None, "")])
    if total == 0:
        total = len(en_flat) or 1

    results = []
    for entry in yml_files:
        name = entry["name"]
        if name == ENGLISH_FILE:
            continue
        code = name[:-4]  # strip .yml
        text = _raw(entry)
        percent = None
        if text is not None:
            try:
                flat = _flatten_yaml(yaml.safe_load(text) or {})
                translated = sum(
                    1 for k, en_v in en_flat.items()
                    if _is_translated(flat.get(k), en_v)
                )
                percent = round(translated * 100 / total)
            except yaml.YAMLError as e:
                log.warning("translations(%s): could not parse %s: %s", repo, name, e)
        results.append({
            "code": code,
            "name": LANGUAGE_NAMES.get(code, code),
            "url": (
                f"https://github.com/{GITHUB_ORG}/{repo}/blob/{branch}/"
                f"{LOCALES_PATH}/{name}"
            ),
            "percent": percent,
        })

    # Sort by display name for stable, readable output.
    results.sort(key=lambda x: x["name"].lower())
    _translations_cache[cache_key] = results
    return results


# ── Org-wide policy pages ────────────────────────────────────────────
# Pulls the canonical policy documents from the BentoBoxWorld/.github repo
# at build time so this site never carries a stale copy. Each entry maps
# the filename in that repo to the local doc page that mirrors it, so
# cross-references between the policies can be rewritten to work here too.
POLICY_REPO = ".github"
POLICY_BRANCH = "master"
POLICY_LOCAL_PAGES = {
    "PRIVACY.md": "Privacy.md",
    "AI_POLICY.md": "AI-Policy.md",
    "CODE_OF_CONDUCT.md": "CodeOfConduct.md",
    "CONTRIBUTING.md": "Contributing.md",
}
_POLICY_LINK_RE = re.compile(
    r"\]\((" + "|".join(re.escape(name) for name in POLICY_LOCAL_PAGES) + r")(#[^)\s]*)?\)"
)

_policy_cache: dict = {}


def _rewrite_policy_links(text: str) -> str:
    """Point relative links between policy files at their local doc pages
    instead of the bare filenames, which only resolve on GitHub."""
    return _POLICY_LINK_RE.sub(
        lambda m: f"]({POLICY_LOCAL_PAGES[m.group(1)]}{m.group(2) or ''})", text
    )


def _fetch_policy_markdown(filename: str):
    """Fetch a policy file's raw Markdown from BentoBoxWorld/.github. Cached
    per build; returns None (rather than raising) on any failure so a single
    flaky fetch doesn't break the whole site build."""
    if filename in _policy_cache:
        return _policy_cache[filename]

    url = (
        f"https://raw.githubusercontent.com/{GITHUB_ORG}/{POLICY_REPO}/"
        f"{POLICY_BRANCH}/{filename}"
    )
    try:
        r = requests.get(url, timeout=15)
        text = r.text if r.status_code == 200 else None
        if text is None:
            log.warning("policy(%s): fetch returned %s", filename, r.status_code)
    except Exception as e:
        log.warning("policy(%s): fetch failed: %s", filename, e)
        text = None

    _policy_cache[filename] = text
    return text


def define_env(env):

    @env.macro
    def translations(repo: str, branch: str = "develop"):
        intro = (
            '!!! note "Help us keep translations accurate"\n'
            "    Most BentoBox and addon translations are now generated with the\n"
            "    help of AI, so the bulk of the work is already done — but **AI is\n"
            "    not perfect**. What we really need from the community is **error\n"
            "    reports and corrections**.\n"
            "\n"
            "    * Spotted a mistake or awkward phrasing? Open an issue or a PR on\n"
            "    the relevant repository at [bentobox.world](https://bentobox.world)\n"
            "    (a short link to our GitHub org), or tell us on\n"
            "    [Discord](https://discord.bentobox.world).\n"
            "    * Want to add a brand-new language? Open a PR adding a new locale\n"
            "    file to `src/main/resources/locales/` in the relevant repo, or ask\n"
            "    on Discord and we'll get you started.\n"
            "\n"
        )

        en_url = (
            f"https://github.com/{GITHUB_ORG}/{repo}/blob/{branch}/"
            f"{LOCALES_PATH}/{ENGLISH_FILE}"
        )
        header = (
            "| Language | Language code | Progress |\n"
            "| ---------- | --- | ----------- |\n"
            f"| [English (United States)]({en_url}) | `en-US` | 100% (Default) |\n"
        )

        rows = _fetch_translation_status(repo, branch)
        if rows == "missing":
            # No locales/ directory in the repo — this addon currently has
            # no translatable strings.
            note = (
                f"\n_This project does not yet have any translatable locale "
                f"files. Only English is shipped at the moment._\n"
            )
            return intro + header + note
        if rows is None:
            # Network/parse failure — render a graceful fallback that still
            # links to the locales directory on GitHub.
            locales_url = (
                f"https://github.com/{GITHUB_ORG}/{repo}/tree/{branch}/"
                f"{LOCALES_PATH}"
            )
            fallback = (
                f"\n_Translation status is currently unavailable. "
                f"Browse the locale files directly on "
                f"[GitHub]({locales_url})._\n"
            )
            return intro + header + fallback

        body = ""
        for row in rows:
            pct = f"{row['percent']}%" if row["percent"] is not None else "?"
            body += (
                f"| [{row['name']}]({row['url']}) | `{row['code']}` | {pct} |\n"
            )
        return intro + header + body

    @env.macro
    def addon_description(addon_name:str, beta:bool=False):
        result = ""

        if beta:
            result += f"""!!! warning
    **{addon_name}** is currently in **Beta**.\n
    Keep in mind that **you are more likely to encounter bugs** and **some features might not be stable**.\n\n"""

        result += f"""!!! info "Useful links"
    - [GitHub repository](https://github.com/BentoBoxWorld/{addon_name})
    ([Releases](https://github.com/BentoBoxWorld/{addon_name}/releases))
    - [Issue tracker](https://github.com/BentoBoxWorld/{addon_name}/issues)
    - [Development builds](https://ci.codemc.io/job/BentoBoxWorld/job/{addon_name})
    ([Latest stable build](https://ci.codemc.io/job/BentoBoxWorld/job/{addon_name}/lastStableBuild/))"""

        return result

    @env.macro
    def placeholders_bundle(gamemode_name:str):
        result = ""
        source = ""

        # Let's read the csv file
        with open('data/placeholders.csv', newline='') as csvfile:
            reader = csv.DictReader(csvfile)
            for row in reader:
                # Analyze the source
                if (row['source'] != source):
                    if ("[gamemode]" in row['placeholder'] or gamemode_name in row['placeholder']):
                        # We are in a new "source" so we have to put the header
                        source = row['source']
                        result += f"""\n## {source} placeholders

| Placeholder | Description | {source} version
| ---------- | ---------- | ---------- |
"""

                if ("[gamemode]" in row['placeholder'] or gamemode_name in row['placeholder']):
                    result += f"| `%{row['placeholder'].replace('[gamemode]',gamemode_name)}%` | {row['desc']} | {row['version']} |\n"

        return result

    # Adds placeholder table to the addon pages.
    @env.macro
    def placeholders_source(source:str):
        result = f"""!!! tip "Tip"\n
    `[gamemode]` is a prefix that differs depending on the gamemode you are running.\n
    The prefix is the lowercased name of the gamemode, i.e. if you are using BSkyBlock, the prefix is `bskyblock`.\n\n
    Properly translated placeholders for each gamemode can be found:\n
    - [AcidIsland](/en/latest/gamemodes/AcidIsland/Placeholders)
    - [AOneBlock](/en/latest/gamemodes/AOneBlock/Placeholders)
    - [Boxed](/en/latest/gamemodes/Boxed/Placeholders)
    - [BSkyBlock](/en/latest/gamemodes/BSkyBlock/Placeholders)
    - [CaveBlock](/en/latest/gamemodes/CaveBlock/Placeholders)
    - [SkyGrid](/en/latest/gamemodes/SkyGrid/Placeholders).\n
    Please read the main [Placeholders page](/en/latest/BentoBox/Placeholders).\n\n"""

        result += f"""\n

| Placeholder | Description | {source} version
| ---------- | ---------- | ---------- |
"""

        # Let's read the csv file
        with open('data/placeholders.csv', newline='') as csvfile:
            reader = csv.DictReader(csvfile)
            for row in reader:
                # Analyze the source
                if (row['source'] == source):
                    # We are in our plugin, populate rows
                    result += f"| `%{row['placeholder']}%` | {row['desc']} | {row['version']} |\n"

        return result


    # Creates a table of requested flags type.
    @env.macro
    def flags_bundle(type:str):
        result = ""
        source = ""

        # Let's read the csv file
        with open('data/flags.csv', newline='') as csvfile:
            reader = csv.DictReader(csvfile)
            for row in reader:
                # Analyze the source
                if (row['source'] != source):
                    # We are in a new "source" so we have to put the header
                    source = row['source']

                    if (row['type'] == type) or (type == "WORLD_DEFAULT_PROTECTION" and row['type'] == "PROTECTION"):
                        if (type == "PROTECTION"):
                            result += f"""\n## {source} {type.replace("_", " ").capitalize()} flags
    
| | Flag ID | Flag | Description | Default | Min Rank | Max Rank |
| - | ---------- | ---------- | ---------- | ---------- | ---------- | ---------- |
"""
                        else:
                            result += f"""\n## {source} {type.replace("_", " ").capitalize()} flags
    
| | Flag ID | Flag | Description | Default |
| - | ---------- | ---------- | ---------- | ---------- |
"""

                if (row['type'] == type) or (type == "WORLD_DEFAULT_PROTECTION" and row['type'] == "PROTECTION"):
                    if (type == "PROTECTION"):
                        result += f"| <span class='icon-minecraft {icon_css(row['icon'])}'></span> | {row['flag']} | {row['name']} | {row['description']} | {row['default']} | {row['min']} | {row['max']} |\n"
                    else:
                        result += f"| <span class='icon-minecraft {icon_css(row['icon'])}'></span> | {row['flag']} | {row['name']} | {row['description']} | {row['default']} |\n"

        return result


    # Creates a table of requested flags type.
    @env.macro
    def flags_source(source:str, type:str):
        result = ""

        # Let's read the csv file
        with open('data/flags.csv', newline='') as csvfile:
            reader = csv.DictReader(csvfile)
            for row in reader:
                # Analyze the source
                if (row['source'] == source):
                    # We are in a new "source" so we have to put the header

                    if (row['type'] == type) or (type == "WORLD_DEFAULT_PROTECTION" and row['type'] == "PROTECTION"):
                        if (type == "PROTECTION"):
                            result += f"""\n## {source} {type.replace("_", " ").capitalize()} flags
    
| | Flag ID | Flag | Description | Default | Min Rank | Max Rank |
| - | ---------- | ---------- | ---------- | ---------- | ---------- | ---------- |
"""

                            result += f"| <span class='icon-minecraft {icon_css(row['icon'])}'></span> | {row['flag']} | {row['name']} | {row['description']} | {row['default']} | {row['min']} | {row['max']} |\n"
                        else:
                            result += f"""\n## {source} {type.replace("_", " ").capitalize()} flags
    
| | Flag ID | Flag | Description | Default |
| - | ---------- | ---------- | ---------- | ---------- |
"""
                            result += f"| <span class='icon-minecraft {icon_css(row['icon'])}'></span> | {row['flag']} | {row['name']} | {row['description']} | {row['default']} |\n"

        return result

    @env.macro
    def policy_page(filename: str):
        source_url = (
            f"https://github.com/{GITHUB_ORG}/{POLICY_REPO}/blob/"
            f"{POLICY_BRANCH}/{filename}"
        )
        text = _fetch_policy_markdown(filename)
        if text is None:
            return (
                '!!! warning "Could not load this page"\n'
                "    This page is normally pulled automatically from "
                f"[{filename} in BentoBoxWorld/.github]({source_url}) when "
                "the site is built, but the fetch failed this time. View "
                f"it directly on [GitHub]({source_url}) instead.\n"
            )

        note = (
            '!!! note "Synced from GitHub"\n'
            "    This page is pulled automatically from "
            f"[{filename} in BentoBoxWorld/.github]({source_url}) every "
            "time the documentation site is built, so it always matches "
            "the canonical, org-wide policy.\n\n"
        )
        return note + _rewrite_policy_links(text)

    # Creates a table of requested flags type.
    @env.macro
    def icon_css(icon:str):
        with open("data/minecraft-block-and-entity.json", 'r') as j:
            contents = json.loads(j.read())

            for entry in contents:
                if icon.lower() == entry['name']:
                    return entry['css']

        return ""