Add scripts to allow addons from personal repos to be synchronized with Crowdin

.github/scripts/checkTranslation.py

@@ -0,0 +1,125 @@
+import sys
+import os
+from crowdin_api import CrowdinClient
+
+def find_file_id(client, project_id, base_target, search_ext):
+	"""
+	Iterates through all project files (using pagination) to find the ID
+	of the source file matching the target name and extension.
+	"""
+	offset = 0
+	limit = 100
+
+	while True:
+		resp = client.source_files.list_files(
+			projectId=project_id,
+			limit=limit,
+			offset=offset
+		)
+
+		data = resp['data']
+		for f in data:
+			path_crowdin = f['data']['path'].lower()
+			# Check if the path ends with addon_id.pot or addon_id.xliff
+			if path_crowdin.endswith(f"{base_target}{search_ext}"):
+				file_id = f['data']['id']
+				print(f"DEBUG: Match found: {path_crowdin} (ID: {file_id})")
+				return file_id
+
+		if len(data) < limit:
+			break
+
+		offset += limit
+
+	return None
+
+def get_score_from_api(file_name_to_search: str, lang_id: str) -> float:
+	"""
+	Retrieves the translation progress score for a specific language and file.
+	Handles pagination for both file listing and language status.
+	"""
+	token = os.environ.get("crowdinAuthToken")
+	p_id_env = os.environ.get("CROWDIN_PROJECT_ID")
+
+	if not token or not p_id_env:
+		print("ERROR: Missing environment variables 'crowdinAuthToken' or 'CROWDIN_PROJECT_ID'.")
+		return 0.0
+
+	client = CrowdinClient(token=token)
+	p_id = int(p_id_env)
+
+	try:
+		# Clean and prepare search patterns
+		# Example: 'addon/locale/fr/LC_MESSAGES/myaddon.po' -> base_target: 'myaddon'
+		base_target = file_name_to_search.replace('\\', '/').split('/')[-1].rsplit('.', 1)[0].lower()
+		ext_target = file_name_to_search.split('.')[-1].lower()
+
+		# On Crowdin, the source for a .po file is usually a .pot file
+		search_ext = ".pot" if ext_target == "po" else f".{ext_target}"
+
+		print(f"DEBUG: Searching for source file: {base_target}{search_ext}")
+
+		file_id = find_file_id(client, p_id, base_target, search_ext)
+
+		if file_id is None:
+			print(f"WARNING: File '{base_target}{search_ext}' not found on Crowdin.")
+			return 0.0
+
+		# Pagination for translation status (Progress)
+		offset = 0
+		limit = 100
+
+		while True:
+			resp = client.translation_status.get_file_progress(
+				projectId=p_id,
+				fileId=file_id,
+				limit=limit,
+				offset=offset
+			)
+
+			data = resp['data']
+			for item in data:
+				lang_api = item['data']['languageId']
+
+				# Flexible matching (e.g., 'fr' will match 'fr' or 'fr-FR' from API)
+				# Also handles underscore to dash conversion for Crowdin compatibility
+				if lang_api.lower().startswith(lang_id.lower().replace('_', '-')):
+					progress = float(item['data']['translationProgress'])
+					return progress / 100
+
+			# Check pagination total
+			total = resp['pagination']['totalCount']
+			if offset + limit >= total:
+				break
+			offset += limit
+
+		print(f"DEBUG: Language '{lang_id}' not found in progress list for this file.")
+		return 0.0
+
+	except Exception as e:
+		print(f"API ERROR: {e}")
+		return 0.0
+
+def main():
+	if len(sys.argv) < 3:
+		print("Usage: python checkTranslation.py <file_path> <lang_id>")
+		sys.exit(2)
+
+	input_file = sys.argv[1]
+	lang = sys.argv[2]
+
+	score = get_score_from_api(input_file, lang)
+
+	# Output formatted for capture by the PowerShell script (crowdinSync.ps1)
+	print(f"translationRatio={score}")
+
+	if input_file.lower().endswith('.md'):
+		print(f"mdScore={score}")
+	else:
+		print(f"poScore={score}")
+
+	# Exit with success (0) if there is at least some translated content
+	sys.exit(0 if score > 0.05 else 1)
+
+if __name__ == "__main__":
+	main()

.github/scripts/crowdinSync.ps1

@@ -0,0 +1,166 @@
+#!/usr/bin/env pwsh
+$ErrorActionPreference = 'Stop'
+
+# Git configuration for automated commits
+git config user.name "github-actions[bot]"
+git config user.email "github-actions[bot]@users.noreply.github.com"
+
+$addonId = $env:ADDON_ID.Trim()
+if (-not $addonId) {
+    Write-Error "Failed to get addon ID."
+    exit 1
+}
+
+# --- STEP 1: PREPARATION AND SOURCE UPDATE ---
+
+$xliffFile = "./$addonId.xliff"
+$mdFile = "./readme.md"
+
+if (Test-Path $mdFile) {
+    if (Test-Path $xliffFile) {
+        $tempXliff = [System.IO.Path]::GetTempFileName()
+        Copy-Item "$addonId.xliff" $tempXliff -Force
+        Write-Host "DEBUG: Updating XLIFF source based on readme.md..."
+        uv run .github/scripts/markdownTranslate.py updateXliff -m $mdFile -x $tempXliff -o $xliffFile
+    } else {
+        Write-Host "DEBUG: XLIFF template not found. Creating new one from readme.md..."
+        uv run .github/scripts/markdownTranslate.py generateXliff -m $mdFile -o $xliffFile
+    }
+}
+
+# Update POT file (addon interface)
+uv run scons pot
+$potFile = "$addonId.pot"
+
+# --- STEP 2: UPLOAD SOURCES TO CROWDIN ---
+
+if (Test-Path $potFile) {
+    Write-Host "DEBUG: Uploading updated POT source to Crowdin..."
+    ./l10nUtil.exe uploadSourceFile "$potFile" -c addon
+}
+
+if (Test-Path $xliffFile) {
+    Write-Host "DEBUG: Uploading updated XLIFF source to Crowdin..."
+    ./l10nUtil.exe uploadSourceFile "$xliffFile" -c addon
+    git add "$xliffFile"
+    git diff --staged --quiet
+    if ($LASTEXITCODE -ne 0) {
+        git commit -m "Update $xliffFile for $addonId"
+        git push
+    }
+}
+
+# --- STEP 3: EXPORT AND PROCESS TRANSLATIONS ---
+
+Write-Host "DEBUG: Exporting translations from Crowdin..."
+./l10nUtil.exe exportTranslations -o _addonL10n -c addon
+
+# Ensure base directories exist
+New-Item -ItemType Directory -Force -Path addon/locale | Out-Null
+New-Item -ItemType Directory -Force -Path addon/doc | Out-Null
+
+# Load language mappings for Crowdin API calls
+$languageMappings = Get-Content -Raw ".github/scripts/languageMappings.json" | ConvertFrom-Json
+
+foreach ($dir in Get-ChildItem -Path "_addonL10n/$addonId" -Directory) {
+    $langCode = $dir.Name 
+
+    if ($langCode -eq "en") { continue }
+
+    # Identify codes
+    $crowdinLang = $languageMappings[$langCode]
+    if (-not $crowdinLang) { $crowdinLang = $langCode }
+    $langShort = $langCode.Split('-')[0].Split('_')[0]
+
+    # Map to local NVDA directory
+    $localLangDir = uv run python .github/scripts/langCodes.py $langCode
+
+    Write-Host "`n--- Processing Language: $langCode (Mapped to local: $localLangDir) ---"
+
+    # Paths
+    $remoteMd = Join-Path $dir.FullName "$addonId.md"
+    $remoteXliff = Join-Path $dir.FullName "$addonId.xliff"
+    $remotePo = Join-Path $dir.FullName "$addonId.po"
+    $localMdDir = "addon/doc/$localLangDir"
+    $localMd = "$localMdDir/readme.md"
+    $localPoPath = "addon/locale/$localLangDir/LC_MESSAGES/nvda.po"
+
+    # --- 3.1 PO FILE PROCESSING ---
+    $poImported = $false
+    if (Test-Path $remotePo) {
+        Write-Host "DEBUG: Checking Remote PO progress for $langShort..."
+        uv run python .github/scripts/checkTranslation.py "$addonId.po" $langShort
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "SUCCESS: Remote PO is valid. Importing to $localPoPath"
+            New-Item -ItemType Directory -Force -Path (Split-Path $localPoPath) | Out-Null
+            Move-Item $remotePo $localPoPath -Force
+            $poImported = $true
+        } else {
+            Write-Host "WARNING: Remote PO progress is below threshold."
+        }
+    }
+
+    if (-not $poImported -and (Test-Path $localPoPath)) {
+        Write-Host "ACTION: Uploading local legacy PO to Crowdin ($crowdinLang) as fallback."
+        ./l10nUtil.exe uploadTranslationFile $crowdinLang "$addonId.po" $localPoPath -c addon
+    }
+
+    # --- 3.2 DOCUMENTATION PROCESSING (MD & XLIFF) ---
+    $scoreMd = 0.0
+    $scoreXliff = 0.0
+
+    if (Test-Path $remoteMd) {
+        Write-Host "DEBUG: Evaluating Remote Markdown score..."
+        $res = uv run python .github/scripts/checkTranslation.py "$addonId.md" $langShort
+        $scoreMd = [double]($res | Select-String "mdScore=").ToString().Split("=")[1]
+    } else {
+        Write-Host "DEBUG: No remote Markdown file found for this language."
+    }
+
+    if (Test-Path $remoteXliff) {
+        Write-Host "DEBUG: Evaluating Remote XLIFF score..."
+        $res = uv run python .github/scripts/checkTranslation.py "$addonId.xliff" $langShort
+        $scoreXliff = [double]($res | Select-String "translationRatio=").ToString().Split("=")[1]
+    } else {
+        Write-Host "DEBUG: No remote XLIFF file found for this language."
+    }
+
+    Write-Host "DEBUG: Comparison Scores -> MD: $scoreMd | XLIFF: $scoreXliff"
+
+    $threshold = 0.5
+    $docImported = $false
+
+    if ($scoreXliff -gt $threshold -or $scoreMd -gt $threshold) {
+        if (!(Test-Path $localMdDir)) { New-Item -ItemType Directory -Force -Path $localMdDir | Out-Null }
+
+        if ($scoreXliff -ge $scoreMd) {
+            Write-Host "SUCCESS: XLIFF is better or equal. Converting XLIFF to local MD ($localLangDir)..."
+            ./l10nUtil.exe xliff2md $remoteXliff $localMd
+            $docImported = $true
+        } else {
+            Write-Host "SUCCESS: Markdown is better. Importing Remote MD to local ($localLangDir)..."
+            Move-Item $remoteMd $localMd -Force
+            $docImported = $true
+        }
+    } else {
+        Write-Host "WARNING: Both remote MD and XLIFF scores are below threshold ($threshold)."
+    }
+
+    if (-not $docImported -and (Test-Path $localMd)) {
+        Write-Host "ACTION: Documentation quality too low. Uploading local MD to Crowdin ($crowdinLang) as fallback."
+        ./l10nUtil.exe uploadTranslationFile $crowdinLang "$addonId.md" $localMd -c addon
+    }
+}
+
+# --- STEP 4: COMMIT UPDATED TRANSLATIONS ---
+
+git add addon/locale addon/doc
+git diff --staged --quiet
+if ($LASTEXITCODE -ne 0) {
+    git commit -m "Update translations for $addonId from Crowdin (Automatic Sync)"
+    $branch = $env:downloadTranslationsBranch
+    git push -f origin "HEAD:$branch"
+    Write-Host "SUCCESS: Translations committed and pushed."
+} else {
+    Write-Host "DEBUG: No changes in translations to commit."
+}

.github/scripts/langCodes.py

@@ -0,0 +1,60 @@
+import sys
+
+# Mapping between Crowdin language IDs (keys) and standard NVDA directory names (values).
+# This dictionary acts as the symmetrical counterpart to 'languageMappings.json' implemented by @nvdaes.
+# It ensures that translations exported from Crowdin are stored in the correct 
+# local paths (e.g., 'es-ES' from Crowdin goes into the 'es' folder).
+CROWDIN_TO_NVDA = {
+    # Arabic variants
+    "ar-SA": "ar_SA",
+
+    # Spanish variants
+    "es-ES": "es",
+    "es-CO": "es_CO",
+
+    # Portuguese variants
+    "pt-BR": "pt_BR",
+    "pt-PT": "pt_PT",
+
+    # Chinese variants
+    "zh-CN": "zh_CN",
+    "zh-HK": "zh_HK",
+    "zh-TW": "zh_TW",
+
+    # Other specific mappings from the NVDA ecosystem
+    "af": "af_ZA",
+    "de-CH": "de_CH",
+    "nb": "nb_NO",
+    "nn-NO": "nn_NO",
+    "sr-CS": "sr"
+}
+
+def get_nvda_code(crowdin_code):
+    """
+    Returns the appropriate local directory name for a given Crowdin language ID.
+
+    Args:
+        crowdin_code (str): The language identifier from Crowdin (e.g., 'pt-BR', 'fr').
+
+    Returns:
+        str: The corresponding NVDA locale folder name (e.g., 'pt_BR', 'fr').
+    """
+    # 1. Direct check in our verified map (Priority)
+    if crowdin_code in CROWDIN_TO_NVDA:
+        return CROWDIN_TO_NVDA[crowdin_code]
+
+    # 2. Automated conversion for regional variants: Crowdin "xx-YY" -> NVDA "xx_YY"
+    # This handles regional codes not explicitly defined in the map.
+    if "-" in crowdin_code:
+        return crowdin_code.replace("-", "_")
+
+    # 3. Default: Return as is.
+    # This covers base languages that don't use regional folders in NVDA 
+    # (e.g., 'fr', 'tr', 'bg', 'fi', 'fa').
+    return crowdin_code
+
+if __name__ == "__main__":
+    # Ensure a language code was provided as a command-line argument
+    if len(sys.argv) > 1:
+        # Standardize input and output the mapped code for PowerShell to capture
+        print(get_nvda_code(sys.argv[1]))

.github/scripts/languageMappings.json

@@ -0,0 +1,14 @@
+{
+	"af_ZA": "af",
+	"de_CH": "de-CH",
+	"es": "es-ES",
+	"es_CO": "es-CO",
+	"nb_NO": "nb",
+	"nn_NO": "nn-NO",
+	"pt_PT": "pt-PT",
+	"pt_BR": "pt-BR",
+	"sr": "sr-CS",
+	"zh_CN": "zh-CN",
+	"zh_HK": "zh-HK",
+	"zh_TW": "zh-TW"
+}