generate_config_translations.py
Rama dev · réplica de lectura del repositorio original.
#!/usr/bin/env python3
"""
Generate English translation JSON files from Pydantic config models.
This script dynamically extracts all top-level config sections from FrigateConfig
and generates JSON translation files with titles and descriptions for the web UI.
"""
import json
import logging
import sys
from pathlib import Path
from typing import Any, get_args, get_origin
from frigate.config.config import FrigateConfig
from frigate.util.schema import get_config_schema
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
def get_field_translations(field_info) -> dict[str, str]:
"""Extract title and description from a Pydantic field."""
translations = {}
if field_info.title:
translations["label"] = field_info.title
if field_info.description:
translations["description"] = field_info.description
return translations
def extract_translations_from_schema(
schema: dict[str, Any], defs: dict[str, Any] = None
) -> dict[str, Any]:
"""
Recursively extract translations (titles and descriptions) from a JSON schema.
Returns a dictionary structure with label and description for each field,
and nested fields directly under their parent keys.
"""
if defs is None:
defs = schema.get("$defs", {})
translations = {}
# Add top-level title and description if present
if "title" in schema:
translations["label"] = schema["title"]
if "description" in schema:
translations["description"] = schema["description"]
# Process nested properties
properties = schema.get("properties", {})
for field_name, field_schema in properties.items():
field_translations = {}
# Handle $ref references
if "$ref" in field_schema:
ref_path = field_schema["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
ref_schema = defs[ref_name]
# Extract from the referenced schema
ref_translations = extract_translations_from_schema(
ref_schema, defs=defs
)
# Use the $ref field's own title/description if present
if "title" in field_schema:
field_translations["label"] = field_schema["title"]
elif "label" in ref_translations:
field_translations["label"] = ref_translations["label"]
if "description" in field_schema:
field_translations["description"] = field_schema["description"]
elif "description" in ref_translations:
field_translations["description"] = ref_translations[
"description"
]
# Add nested properties from referenced schema
nested_without_root = {
k: v
for k, v in ref_translations.items()
if k not in ("label", "description")
}
field_translations.update(nested_without_root)
# Handle additionalProperties with $ref (for dict types)
elif "additionalProperties" in field_schema:
additional_props = field_schema["additionalProperties"]
# Extract title and description from the field itself
if "title" in field_schema:
field_translations["label"] = field_schema["title"]
if "description" in field_schema:
field_translations["description"] = field_schema["description"]
# If additionalProperties contains a $ref, extract nested translations
if "$ref" in additional_props:
ref_path = additional_props["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
ref_schema = defs[ref_name]
nested = extract_translations_from_schema(ref_schema, defs=defs)
nested_without_root = {
k: v
for k, v in nested.items()
if k not in ("label", "description")
}
field_translations.update(nested_without_root)
# Handle items with $ref (for array types)
elif "items" in field_schema:
items = field_schema["items"]
# Extract title and description from the field itself
if "title" in field_schema:
field_translations["label"] = field_schema["title"]
if "description" in field_schema:
field_translations["description"] = field_schema["description"]
# If items contains a $ref, extract nested translations
if "$ref" in items:
ref_path = items["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
ref_schema = defs[ref_name]
nested = extract_translations_from_schema(ref_schema, defs=defs)
nested_without_root = {
k: v
for k, v in nested.items()
if k not in ("label", "description")
}
field_translations.update(nested_without_root)
else:
# Extract title and description
if "title" in field_schema:
field_translations["label"] = field_schema["title"]
if "description" in field_schema:
field_translations["description"] = field_schema["description"]
# Recursively process nested properties
if "properties" in field_schema:
nested = extract_translations_from_schema(field_schema, defs=defs)
# Merge nested translations
nested_without_root = {
k: v for k, v in nested.items() if k not in ("label", "description")
}
field_translations.update(nested_without_root)
# Handle anyOf cases
elif "anyOf" in field_schema:
for item in field_schema["anyOf"]:
nested = None
if item.get("type") == "null":
continue
if "properties" in item:
nested = extract_translations_from_schema(item, defs=defs)
elif "$ref" in item:
ref_path = item["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested = extract_translations_from_schema(
defs[ref_name], defs=defs
)
elif (
"additionalProperties" in item
and isinstance(item["additionalProperties"], dict)
and "$ref" in item["additionalProperties"]
):
ref_path = item["additionalProperties"]["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested = extract_translations_from_schema(
defs[ref_name], defs=defs
)
elif (
"items" in item
and isinstance(item["items"], dict)
and ("$ref" in item["items"])
):
ref_path = item["items"]["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested = extract_translations_from_schema(
defs[ref_name], defs=defs
)
if nested:
nested_without_root = {
k: v
for k, v in nested.items()
if k not in ("label", "description")
}
field_translations.update(nested_without_root)
if field_translations:
translations[field_name] = field_translations
return translations
def generate_section_translation(config_class: type) -> dict[str, Any]:
"""
Generate translation structure for a config section using its JSON schema.
"""
schema = config_class.model_json_schema()
return extract_translations_from_schema(schema)
def main():
"""Main function to generate config translations."""
# Define output directory
if len(sys.argv) > 1:
output_dir = Path(sys.argv[1])
else:
output_dir = (
Path(__file__).parent / "web" / "public" / "locales" / "en" / "config"
)
logger.info(f"Output directory: {output_dir}")
# Ensure the output directory exists; do not delete existing files.
output_dir.mkdir(parents=True, exist_ok=True)
logger.info(
f"Using output directory (existing files will be overwritten): {output_dir}"
)
config_fields = FrigateConfig.model_fields
config_schema = get_config_schema(FrigateConfig)
logger.info(f"Found {len(config_fields)} top-level config sections")
global_translations = {}
for field_name, field_info in config_fields.items():
if field_name.startswith("_"):
continue
logger.info(f"Processing section: {field_name}")
# Get the field's type
field_type = field_info.annotation
from typing import Optional, Union
origin = get_origin(field_type)
if (
origin is Optional
or origin is Union
or (
hasattr(origin, "__name__")
and origin.__name__ in ("UnionType", "Union")
)
):
args = get_args(field_type)
field_type = next(
(arg for arg in args if arg is not type(None)), field_type
)
# Handle Dict[str, SomeModel] - extract the value type
if origin is dict:
args = get_args(field_type)
if args and len(args) > 1:
field_type = args[1] # Get value type from Dict[key, value]
# Handle List[SomeModel] - extract the item type
if origin is list:
args = get_args(field_type)
if args:
field_type = args[0]
# Start with field's top-level metadata (label, description)
section_data = get_field_translations(field_info)
# Generate nested translations from the field type's schema
if hasattr(field_type, "model_json_schema"):
schema = field_type.model_json_schema()
# Extract nested properties from schema
nested = extract_translations_from_schema(schema)
# Remove top-level label/description from nested since we got those from field_info
nested_without_root = {
k: v for k, v in nested.items() if k not in ("label", "description")
}
section_data.update(nested_without_root)
if field_name == "objects":
# Produce a parallel `filters_attribute` block alongside `filters`,
# with object-wording rewritten for attribute filters (face,
# license_plate, courier logos). The frontend's
# buildTranslationPath routes `filters.<attr>.<field>` lookups to
# `filters_attribute.<field>` when `<attr>` is in
# `model.all_attributes`. Keep this rewrite list explicit rather
# than running a blanket s/object/attribute/ so unrelated
# descriptions (e.g. "JSON object") never accidentally flip.
filters_block = section_data.get("filters")
if isinstance(filters_block, dict):
attribute_rewrites = [
("Object filters", "Attribute filters"),
("detected objects", "detected attributes"),
("object area", "attribute area"),
("object type", "attribute"),
("the object", "the attribute"),
]
# Per-field overrides for cases where the generic rewrite
# doesn't capture the attribute-specific semantics. Keys
# match the FilterConfig field name; values are partial
# overrides applied AFTER the generic rewrites.
attribute_field_overrides: dict[str, dict[str, str]] = {
"min_score": {
"description": (
"Minimum single-frame detection confidence required "
"to associate this attribute with its parent object."
),
},
}
def rewrite(text: str) -> str:
for source, replacement in attribute_rewrites:
text = text.replace(source, replacement)
return text
attribute_variant: dict[str, Any] = {}
for key, value in filters_block.items():
if key in ("label", "description"):
if isinstance(value, str):
attribute_variant[key] = rewrite(value)
continue
if not isinstance(value, dict):
continue
field_trans: dict[str, str] = {}
if isinstance(value.get("label"), str):
field_trans["label"] = rewrite(value["label"])
if isinstance(value.get("description"), str):
field_trans["description"] = rewrite(value["description"])
overrides = attribute_field_overrides.get(key)
if overrides:
field_trans.update(overrides)
if field_trans:
attribute_variant[key] = field_trans
if attribute_variant:
section_data["filters_attribute"] = attribute_variant
if not section_data:
logger.warning(f"No translations found for section: {field_name}")
continue
# Add camera-level fields to global config documentation if applicable
CAMERA_LEVEL_FIELDS = {
"birdseye": (
"frigate.config.camera.birdseye",
"BirdseyeCameraConfig",
["order"],
),
"ffmpeg": (
"frigate.config.camera.ffmpeg",
"CameraFfmpegConfig",
["inputs"],
),
"lpr": (
"frigate.config.classification",
"CameraLicensePlateRecognitionConfig",
["expire_time"],
),
"semantic_search": (
"frigate.config.classification",
"CameraSemanticSearchConfig",
["triggers"],
),
}
if field_name in CAMERA_LEVEL_FIELDS:
module_path, class_name, field_names = CAMERA_LEVEL_FIELDS[field_name]
try:
import importlib
module = importlib.import_module(module_path)
camera_class = getattr(module, class_name)
schema = camera_class.model_json_schema()
camera_fields = schema.get("properties", {})
defs = schema.get("$defs", {})
for fname in field_names:
if fname in camera_fields:
field_schema = camera_fields[fname]
field_trans = {}
if "title" in field_schema:
field_trans["label"] = field_schema["title"]
if "description" in field_schema:
field_trans["description"] = field_schema["description"]
# Extract nested properties based on schema type
nested_to_extract = None
# Handle direct $ref
if "$ref" in field_schema:
ref_path = field_schema["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested_to_extract = defs[ref_name]
# Handle additionalProperties with $ref (for dict types)
elif "additionalProperties" in field_schema:
additional_props = field_schema["additionalProperties"]
if "$ref" in additional_props:
ref_path = additional_props["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested_to_extract = defs[ref_name]
# Handle items with $ref (for array types)
elif "items" in field_schema:
items = field_schema["items"]
if "$ref" in items:
ref_path = items["$ref"]
if ref_path.startswith("#/$defs/"):
ref_name = ref_path.split("/")[-1]
if ref_name in defs:
nested_to_extract = defs[ref_name]
# Extract nested properties if we found a schema to use
if nested_to_extract:
nested = extract_translations_from_schema(
nested_to_extract, defs=defs
)
nested_without_root = {
k: v
for k, v in nested.items()
if k not in ("label", "description")
}
field_trans.update(nested_without_root)
if field_trans:
section_data[fname] = field_trans
except Exception as e:
logger.warning(
f"Could not add camera-level fields for {field_name}: {e}"
)
# Add to global translations instead of writing separate files
global_translations[field_name] = section_data
logger.info(f"Added section to global translations: {field_name}")
# Handle camera-level configs that aren't top-level FrigateConfig fields
# These are defined as fields in CameraConfig, so we extract title/description from there
camera_level_configs = {
"camera_mqtt": ("frigate.config.camera.mqtt", "CameraMqttConfig", "mqtt"),
"camera_ui": ("frigate.config.camera.ui", "CameraUiConfig", "ui"),
"onvif": ("frigate.config.camera.onvif", "OnvifConfig", "onvif"),
}
# Import CameraConfig to extract field metadata
from frigate.config.camera.camera import CameraConfig
camera_config_schema = CameraConfig.model_json_schema()
camera_properties = camera_config_schema.get("properties", {})
for config_name, (
module_path,
class_name,
camera_field_name,
) in camera_level_configs.items():
try:
logger.info(f"Processing camera-level section: {config_name}")
import importlib
module = importlib.import_module(module_path)
config_class = getattr(module, class_name)
section_data = {}
# Extract top-level label and description from CameraConfig field definition
if camera_field_name in camera_properties:
field_schema = camera_properties[camera_field_name]
if "title" in field_schema:
section_data["label"] = field_schema["title"]
if "description" in field_schema:
section_data["description"] = field_schema["description"]
# Process model fields from schema
schema = config_class.model_json_schema()
nested = extract_translations_from_schema(schema)
# Remove top-level label/description since we got those from CameraConfig
nested_without_root = {
k: v for k, v in nested.items() if k not in ("label", "description")
}
section_data.update(nested_without_root)
# Add camera-level section into global translations (do not write separate file)
global_translations[config_name] = section_data
logger.info(
f"Added camera-level section to global translations: {config_name}"
)
except Exception as e:
logger.error(f"Failed to generate {config_name}: {e}")
# Remove top-level 'cameras' field if present so it remains a separate file
if "cameras" in global_translations:
logger.info(
"Removing top-level 'cameras' from global translations to keep it as a separate cameras.json"
)
del global_translations["cameras"]
# Write consolidated global.json with per-section keys
global_file = output_dir / "global.json"
with open(global_file, "w", encoding="utf-8") as f:
json.dump(global_translations, f, indent=2, ensure_ascii=False)
f.write("\n")
logger.info(f"Generated consolidated translations: {global_file}")
if not global_translations:
logger.warning("No global translations were generated!")
else:
logger.info(f"Global contains {len(global_translations)} sections")
# Generate cameras.json from CameraConfig schema
cameras_file = output_dir / "cameras.json"
logger.info(f"Generating cameras.json: {cameras_file}")
try:
if "camera_config_schema" in locals():
camera_schema = camera_config_schema
else:
from frigate.config.camera.camera import CameraConfig
camera_schema = CameraConfig.model_json_schema()
camera_translations = extract_translations_from_schema(camera_schema)
# Change descriptions to use 'for this camera' for fields that are global
def sanitize_camera_descriptions(obj):
if isinstance(obj, dict):
for k, v in list(obj.items()):
if k == "description" and isinstance(v, str):
obj[k] = v.replace(
"for all cameras; can be overridden per-camera",
"for this camera",
)
else:
sanitize_camera_descriptions(v)
elif isinstance(obj, list):
for item in obj:
sanitize_camera_descriptions(item)
sanitize_camera_descriptions(camera_translations)
# Profiles contain the same sections as the camera itself; only keep
# label and description to avoid duplicating every camera section.
if "profiles" in camera_translations:
camera_translations["profiles"] = {
k: v
for k, v in camera_translations["profiles"].items()
if k in ("label", "description")
}
with open(cameras_file, "w", encoding="utf-8") as f:
json.dump(camera_translations, f, indent=2, ensure_ascii=False)
f.write("\n")
logger.info(f"Generated cameras.json: {cameras_file}")
except Exception as e:
logger.error(f"Failed to generate cameras.json: {e}")
logger.info("Translation generation complete!")
if __name__ == "__main__":
main()