Coverage for src / ezqt_app / services / translation / helpers.py: 67.57%

1# /////////////////////////////////////////////////////////////// 

2# SERVICES.TRANSLATION.HELPERS - Translation convenience functions 

3# Project: ezqt_app 

4# /////////////////////////////////////////////////////////////// 

5 

6"""Thin helper functions over TranslationManager for ergonomic API access.""" 

7 

8from __future__ import annotations 

9 

10# /////////////////////////////////////////////////////////////// 

11# IMPORTS 

12# /////////////////////////////////////////////////////////////// 

13# Standard library imports 

14from typing import Any 

15 

16# Local imports 

17from .manager import get_translation_manager 

18 

19 

20# /////////////////////////////////////////////////////////////// 

21# TRANSLATION HELPERS 

22# /////////////////////////////////////////////////////////////// 

23def tr(text: str) -> str: 

24 """Translate *text* using the active language context.""" 

25 return get_translation_manager().translate(text) 

26 

27 

28def change_language(language_name: str) -> bool: 

29 """Switch the application language by display name (e.g. ``"Français"``).""" 

30 return get_translation_manager().load_language(language_name) 

31 

32 

33def change_language_by_code(language_code: str) -> bool: 

34 """Switch the application language by ISO code (e.g. ``"fr"``).""" 

35 return get_translation_manager().load_language_by_code(language_code) 

36 

37 

38def get_available_languages() -> list[str]: 

39 """Return list of available language codes.""" 

40 return get_translation_manager().get_available_languages() 

41 

42 

43def get_current_language() -> str: 

44 """Return the current language display name.""" 

45 return get_translation_manager().get_current_language_name() 

46 

47 

48def enable_auto_translation(enabled: bool = True) -> None: 

49 """Enable or disable automatic translation.""" 

50 get_translation_manager().enable_auto_translation(enabled) 

51 

52 

53def get_auto_translation_stats() -> dict[str, Any]: 

54 """Return automatic translation cache statistics.""" 

55 return get_translation_manager().get_auto_translation_stats() 

56 

57 

58def clear_auto_translation_cache() -> None: 

59 """Clear the automatic translation cache.""" 

60 get_translation_manager().clear_auto_translation_cache() 

61 

62 

63# /////////////////////////////////////////////////////////////// 

64# STATS HELPERS 

65# /////////////////////////////////////////////////////////////// 

66def get_translation_stats() -> dict[str, Any]: 

67 """Return complete translation system statistics.""" 

68 manager = get_translation_manager() 

69 return { 

70 "cached_translations": manager.translation_count, 

71 "current_language": manager.get_current_language_name(), 

72 "available_languages": manager.get_available_languages(), 

73 "auto_translation_enabled": manager.auto_translation_enabled, 

74 "auto_translation_stats": manager.get_auto_translation_stats(), 

75 } 

76 

77 

78# /////////////////////////////////////////////////////////////// 

79# STRING COLLECTOR HELPERS 

80# /////////////////////////////////////////////////////////////// 

81def collect_strings_from_widget(widget: Any, recursive: bool = True) -> set[str]: 

82 """Collect all UI strings from *widget* (for translation workflow).""" 

83 from .string_collector import get_string_collector 

84 

85 return get_string_collector().collect_strings_from_widget(widget, recursive) 

86 

87 

88def collect_and_compare_strings(widget: Any, recursive: bool = True) -> dict[str, Any]: 

89 """Collect strings and compare with already-processed ones.""" 

90 from .string_collector import get_string_collector 

91 

92 return get_string_collector().collect_and_compare(widget, recursive) 

93 

94 

95def get_new_strings() -> set[str]: 

96 """Return strings collected but not yet marked as processed.""" 

97 from .string_collector import get_string_collector 

98 

99 return get_string_collector().get_new_strings() 

100 

101 

102def mark_strings_as_processed(strings: set[str] | None = None) -> None: 

103 """Mark *strings* as processed (default: all new strings).""" 

104 from .string_collector import get_string_collector 

105 

106 get_string_collector().mark_strings_as_processed(strings) 

107 

108 

109def get_string_collector_stats() -> dict[str, Any]: 

110 """Return string collector statistics.""" 

111 from .string_collector import get_string_collector 

112 

113 return get_string_collector().get_stats()