Skip to content

Commit 551b5cc

Browse files
muminkoykiranmuminkoykiran
authored
feat: add Turkish language support (#1468)
* feat: add Turkish language support Added comprehensive Turkish (tr) language translations for Xiaomi Home Integration. Changes: - Added custom_components/xiaomi_home/translations/tr.json with complete UI translations - Added custom_components/xiaomi_home/miot/i18n/tr.json with MIoT-specific translations - All placeholders, markdown formatting, and special characters preserved - Validated against English source files for structural integrity Technical details: - Followed Home Assistant language code standards (ISO 639-1: tr) - Maintained formal Turkish (siz form) for professional user experience - Preserved all technical terms (OAuth2, MIoT-Spec-V2, MQTT, etc.) - JSON structure validated and all keys match English version * feat: add Turkish translations to bool_trans.yaml Added Turkish boolean value translations for: - default: true/false values - contact_state: contact/no contact states - motion_state: motion detected states - open_close: open/close states - yes_no: yes/no values * docs: update README to reflect Turkish language support Updated multiple language support section: - Changed from 8 to 13 supported languages - Added Turkish (tr) to the language code list - Updated language list to include all currently supported languages: Italian, Dutch, Portuguese, Brazilian Portuguese, and Turkish * fix: correct language dictionary sorting and update documentation - Sort INTEGRATION_LANGUAGES dictionary alphabetically (tr after ru) - Update CLAUDE.md to reflect 13 supported languages instead of 8 - Fixes test_miot_data_sort() test requirement - No functional changes, documentation and code style improvements only * docs: update Chinese README to reflect 13 supported languages - Changed from 8 to 13 languages in Chinese documentation - Added Turkish, Italian, Dutch, Portuguese, Brazilian Portuguese - Updated language code list to include: it, nl, pt, pt-BR, tr - Changed translation source note from "machine translation" to "machine translation or community contributions" - Maintains consistency with English README.md
1 parent f49e769 commit 551b5cc

7 files changed

Lines changed: 597 additions & 4 deletions

File tree

‎CLAUDE.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Xiaomi Home Integration is an official Home Assistant integration for controlling Xiaomi IoT smart devices. It connects to devices via Xiaomi Cloud (MQTT) or locally through Xiaomi Central Hub Gateway. The integration converts MIoT-Spec-V2 device specifications into Home Assistant entities.
8+
9+
## Development Commands
10+
11+
### Installation & Setup
12+
```bash
13+
# Install to Home Assistant config directory
14+
./install.sh /path/to/config
15+
16+
# Install test dependencies
17+
pip install pytest pytest-asyncio pytest-dependency zeroconf paho.mqtt psutil cryptography slugify
18+
```
19+
20+
### Testing
21+
```bash
22+
# Run all tests
23+
pytest -v -s -m github ./test/
24+
25+
# Run specific test files
26+
pytest -v -s ./test/test_spec.py
27+
pytest -v -s ./test/test_cloud.py
28+
pytest -v -s ./test/test_lan.py
29+
30+
# Check rule format
31+
pytest -v -s -m github ./test/check_rule_format.py
32+
```
33+
34+
### Code Quality
35+
```bash
36+
# Run pylint (follows Google Python Style Guide)
37+
pylint $(git ls-files '*.py')
38+
39+
# Lint specific files
40+
pylint custom_components/xiaomi_home/*.py
41+
```
42+
43+
### Validation
44+
```bash
45+
# HACS validation (run by GitHub Actions)
46+
# Uses: hacs/action@main
47+
48+
# Hassfest validation (run by GitHub Actions)
49+
# Uses: home-assistant/actions/hassfest@master
50+
```
51+
52+
## Architecture Overview
53+
54+
### Core Components (miot/)
55+
56+
The integration is built around the `miot/` core package:
57+
58+
**miot_client.py**: Top-level client instance representing a logged-in Xiaomi user. Each user login creates one MIoTClient. Manages authentication, device list, and message routing.
59+
60+
**miot_cloud.py**: OAuth 2.0 authentication and HTTP API calls to Xiaomi Cloud. Handles token refresh, user info, device control commands, and spec downloads.
61+
62+
**miot_mips.py**: Message bus (MQTT) for subscribing to device property changes and events. Implements both cloud (MipsCloudClient) and local (MipsLocalClient) message handling.
63+
64+
**miot_device.py**: Device entity class. Each MIoT device creates multiple MIoTDevice instances (one per Home Assistant entity). Handles property updates, action execution, and event processing.
65+
66+
**miot_spec.py**: MIoT-Spec-V2 parser. Parses device specifications (URN-based type system) from cloud or local cache. Each spec defines services, properties, events, and actions.
67+
68+
**miot_lan.py**: Local LAN control for IP devices in same network. Discovery and control without cloud (optional).
69+
70+
**miot_mdns.py**: mDNS discovery for Xiaomi Central Hub Gateway services.
71+
72+
**miot_storage.py**: File storage for certificates, device specs, translations, and cached data.
73+
74+
**miot_network.py**: Network status monitoring and IP address detection.
75+
76+
**miot_i18n.py**: Multi-language support (13 languages). Manages translations for entity names.
77+
78+
### Entity Conversion (specs/specv2entity.py)
79+
80+
MIoT-Spec-V2 instances are converted to Home Assistant entities using three mapping dictionaries:
81+
82+
- **SPEC_DEVICE_TRANS_MAP**: Whole-device patterns (e.g., vacuum, humidifier, climate)
83+
- **SPEC_SERVICE_TRANS_MAP**: Service-level patterns (e.g., battery, air-purifier)
84+
- **SPEC_PROP_TRANS_MAP**: Property-level patterns (e.g., temperature, humidity)
85+
86+
Conversion priority: Device > Service > Property > General rules
87+
88+
### Spec Customization Files (miot/specs/)
89+
90+
**spec_filter.yaml**: Filters out MIoT-Spec-V2 instances that should NOT be converted to entities. Uses device URN keys and supports wildcard matching for service/property/event/action IIDs.
91+
92+
**spec_modify.yaml**: Modifies spec instances before conversion (e.g., changing value ranges, access modes).
93+
94+
**multi_lang.json**: Local translation overrides with higher priority than cloud translations. Keyed by device URN (without version).
95+
96+
**spec_add.json**: Additional spec definitions for devices not in cloud database.
97+
98+
**bool_trans.yaml**: Boolean value translation mappings.
99+
100+
After editing spec files, you MUST update conversion rules via Integration CONFIGURE page in Home Assistant.
101+
102+
### Platform Files (custom_components/xiaomi_home/)
103+
104+
Standard Home Assistant platform files (sensor.py, switch.py, climate.py, etc.) implement entity registration and state management. Each platform imports from miot_device.py and creates entity subclasses.
105+
106+
**config_flow.py**: Configuration flow for OAuth login and device selection.
107+
108+
**__init__.py**: Integration setup, entry management, and data structure initialization.
109+
110+
## MIoT-Spec-V2 Concepts
111+
112+
**URN Format**: `urn:<namespace>:<type>:<name>:<value>[:<vendor-product>:<version>]`
113+
- namespace: miot-spec-v2 (Xiaomi), bluetooth-spec (SIG), or vendor-specific
114+
- type: device, service, property, event, action
115+
- name: human-readable identifier (used for mapping)
116+
117+
**IIDs (Instance IDs)**: Decimal identifiers
118+
- siid: Service Instance ID
119+
- piid: Property Instance ID
120+
- eiid: Event Instance ID
121+
- aiid: Action Instance ID
122+
123+
**Instance Code Format**:
124+
```
125+
service:<siid> # service
126+
service:<siid>:property:<piid> # property
127+
service:<siid>:property:<piid>:valuelist:<index> # value list item
128+
service:<siid>:event:<eiid> # event
129+
service:<siid>:action:<aiid> # action
130+
```
131+
132+
## Naming Conventions
133+
134+
From CONTRIBUTING.md:
135+
136+
- **Xiaomi**: Always "Xiaomi" in text. Variables: "xiaomi" or "mi"
137+
- **Xiaomi Home**: Always "Xiaomi Home" in text. Variables: "mihome" or "MiHome"
138+
- **Xiaomi IoT**: Always "MIoT" in text. Variables: "miot" or "MIoT"
139+
- **Home Assistant**: Always "Home Assistant" in text. Variables: "hass" or "hass_xxx"
140+
141+
Mixed Chinese/English: Add space between Chinese and English or use Chinese quotation marks.
142+
143+
## Commit Message Format
144+
145+
```
146+
<type>: <subject>
147+
148+
<body>
149+
150+
<footer>
151+
```
152+
153+
Types: feat, fix, docs, style, refactor, perf, test, chore, revert
154+
155+
Subject: Imperative, present tense. Not capitalized. No period.
156+
157+
Body: Detailed description (mandatory except for docs type).
158+
159+
## Code Style
160+
161+
Follow [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). Use the provided `.pylintrc` for linting.
162+
163+
## Debugging
164+
165+
Enable debug logging in Home Assistant configuration.yaml:
166+
```yaml
167+
logger:
168+
default: critical
169+
logs:
170+
custom_components.xiaomi_home: debug
171+
```
172+
173+
## Control Modes
174+
175+
- **Cloud Control**: MQTT message subscription + HTTP command API
176+
- **Local Control**: Via Xiaomi Central Hub Gateway (firmware 3.3.0_0023+) or LAN control (IP devices only, may be unstable)
177+
178+
Central gateway local control takes priority over LAN control when both are available.
179+
180+
## Multi-Region Support
181+
182+
Regions: China (cn), Europe (eu), India (in), Russia (ru), Singapore (sg), USA (us)
183+
184+
User data is isolated per region. Integration supports multiple regions in same Home Assistant instance.
185+
186+
## Important Files Location
187+
188+
- Integration source: `custom_components/xiaomi_home/`
189+
- Spec mappings: `custom_components/xiaomi_home/miot/specs/specv2entity.py`
190+
- Spec filters: `custom_components/xiaomi_home/miot/specs/spec_filter.yaml`
191+
- Translations: `custom_components/xiaomi_home/translations/` and `custom_components/xiaomi_home/miot/i18n/`
192+
- Tests: `test/`

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -328,7 +328,7 @@ Device information service (urn:miot-spec-v2:service:device-information:00007801
328328

329329
## Multiple Language Support
330330

331-
There are 8 languages available for selection in the config flow language option of Xiaomi Home, including Simplified Chinese, Traditional Chinese, English, Spanish, Russian, French, German, and Japanese. The config flow page in Simplified Chinese and English has been manually reviewed by the developer. Other languages are translated by machine translation. If you want to modify the words and sentences in the config flow page, you need to modify the json file of the certain language in `custom_components/xiaomi_home/translations/` and `custom_components/xiaomi_home/miot/i18n/` directory.
331+
There are 13 languages available for selection in the config flow language option of Xiaomi Home, including Simplified Chinese, Traditional Chinese, English, Spanish, Russian, French, German, Japanese, Italian, Dutch, Portuguese, Brazilian Portuguese, and Turkish. The config flow page in Simplified Chinese and English has been manually reviewed by the developer. Other languages are translated by machine translation or community contributions. If you want to modify the words and sentences in the config flow page, you need to modify the json file of the certain language in `custom_components/xiaomi_home/translations/` and `custom_components/xiaomi_home/miot/i18n/` directory.
332332

333333
When displaying Home Assistant entity name, Xiaomi Home downloads the multiple language file configured by the device vendor from MIoT Cloud, which contains translations for MIoT-Spec-V2 instances of the device. `multi_lang.json` is a locally maintained multiple language dictionary, which has a higher priority than the multiple language file obtained from the cloud and can be used to supplement or modify the multiple language translation of devices.
334334

@@ -346,7 +346,7 @@ The format of `multi_lang.json` is as follows.
346346
347347
The key of `multi_lang.json` dictionary is the urn excluding the "version" field of the MIoT-Spec-V2 device instance.
348348
349-
The language code is zh-Hans, zh-Hant, en, es, ru, fr, de, or ja, corresponding to the 8 selectable languages mentioned above.
349+
The language code is zh-Hans, zh-Hant, en, es, ru, fr, de, ja, it, nl, pt, pt-BR, or tr, corresponding to the 13 selectable languages mentioned above.
350350
351351
The instance code is the code of the MIoT-Spec-V2 instance, which is in the format of:
352352

‎custom_components/xiaomi_home/miot/const.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@
117117
'pt': 'Português',
118118
'pt-BR': 'Português (Brasil)',
119119
'ru': 'Русский',
120+
'tr': 'Türkçe',
120121
'zh-Hans': '简体中文',
121122
'zh-Hant': '繁體中文'
122123
}

‎custom_components/xiaomi_home/miot/i18n/tr.json‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
{
2+
"config": {
3+
"other": {
4+
"devices": "Cihazlar",
5+
"found_central_gateway": ", Yerel Merkezi Hub Ağ Geçidi Bulundu",
6+
"without_room": "Oda atanmamış",
7+
"no_display": "Gösterme"
8+
},
9+
"control_mode": {
10+
"auto": "Otomatik",
11+
"cloud": "Bulut"
12+
},
13+
"statistics_logic": {
14+
"or": "VEYA mantığı",
15+
"and": "VE mantığı"
16+
},
17+
"filter_mode": {
18+
"exclude": "Hariç tut",
19+
"include": "Dahil et"
20+
},
21+
"connect_type": {
22+
"0": "WiFi",
23+
"1": "yunyi cihazı",
24+
"2": "Bulut cihazı",
25+
"3": "ZigBee",
26+
"4": "webSocket",
27+
"5": "Sanal cihaz",
28+
"6": "BLE",
29+
"7": "Yerel AP",
30+
"8": "WiFi+BLE",
31+
"9": "Diğer",
32+
"10": "İşlev eklentisi",
33+
"11": "Hücresel ağ",
34+
"12": "Kablo",
35+
"13": "NB-IoT",
36+
"14": "Üçüncü taraf bulut erişimi",
37+
"15": "Kızılötesi uzaktan kumanda cihazı",
38+
"16": "BLE-Mesh",
39+
"17": "Sanal cihaz grubu",
40+
"18": "Ağ geçidi alt cihazı",
41+
"19": "Güvenlik seviyesi ağ geçidi alt cihazı",
42+
"22": "PLC",
43+
"23": "Yalnızca kablo",
44+
"24": "Matter",
45+
"25": "WiFi+Hücresel ağ"
46+
},
47+
"room_name_rule": {
48+
"none": "Senkronize etme",
49+
"home_room": "Ev Adı ve Oda Adı (Xiaomi Home Yatak Odası)",
50+
"room": "Oda Adı (Yatak Odası)",
51+
"home": "Ev Adı (Xiaomi Home)"
52+
},
53+
"option_status": {
54+
"enable": "Etkinleştir",
55+
"disable": "Devre Dışı Bırak"
56+
},
57+
"binary_mode": {
58+
"text": "Metin Sensör Varlığı",
59+
"bool": "İkili Sensör Varlığı"
60+
},
61+
"device_state": {
62+
"add": "Ekle",
63+
"del": "Kullanılamıyor",
64+
"offline": "Çevrimdışı"
65+
},
66+
"lan_ctrl_config": {
67+
"notice_net_dup": "\r\n**[Bildirim]** Aynı ağa bağlı olabilecek birden fazla ağ kartı algılandı. Lütfen seçime dikkat edin.",
68+
"net_unavailable": "Arayüz kullanılamıyor"
69+
}
70+
},
71+
"oauth2": {
72+
"success": {
73+
"title": "Kimlik Doğrulama Başarılı",
74+
"content": "Lütfen bu sayfayı kapatın ve 'İleri'ye tıklamak için hesap kimlik doğrulama sayfasına geri dönün.",
75+
"button": "Kapat"
76+
},
77+
"fail": {
78+
"title": "Kimlik Doğrulama Başarısız",
79+
"content": "{error_msg}, lütfen bu sayfayı kapatın ve kimlik doğrulama bağlantısına tekrar tıklamak için hesap kimlik doğrulama sayfasına geri dönün.",
80+
"button": "Kapat"
81+
},
82+
"error_msg": {
83+
"-10100": "Geçersiz yanıt parametreleri ('code' veya 'state' alanı boş)",
84+
"-10101": "Geçirilen 'state' alanı uyumsuz"
85+
}
86+
},
87+
"miot": {
88+
"client": {
89+
"invalid_oauth_info": "Kimlik doğrulama bilgileri geçersiz, bulut bağlantısı kullanılamayacak, lütfen Xiaomi Home entegrasyon sayfasına girin, yeniden kimlik doğrulaması yapmak için 'Seçenekler'e tıklayın",
90+
"invalid_device_cache": "Önbellek cihaz bilgileri anormal, lütfen Xiaomi Home entegrasyon sayfasına girin, yerel önbelleği güncellemek için 'Seçenekler->Cihaz listesini güncelle'ye tıklayın",
91+
"invalid_cert_info": "Geçersiz kullanıcı sertifikası, yerel merkezi bağlantı kullanılamayacak, lütfen Xiaomi Home entegrasyon sayfasına girin, yeniden kimlik doğrulaması yapmak için 'Seçenekler'e tıklayın",
92+
"device_cloud_error": "Buluttan cihaz bilgileri alınırken bir istisna oluştu, lütfen yerel ağ bağlantısını kontrol edin",
93+
"xiaomi_home_error_title": "Xiaomi Home Entegrasyon Hatası",
94+
"xiaomi_home_error": "**{nick_name}({uid}, {cloud_server})** hatası algılandı, lütfen yeniden yapılandırmak için seçenekler sayfasına girin.\n\n**Hata mesajı**: \n{message}",
95+
"device_list_changed_title": "Xiaomi Home cihaz listesi değişiklikleri",
96+
"device_list_changed": "**{nick_name}({uid}, {cloud_server})** cihaz bilgilerinin değiştiği algılandı, lütfen entegrasyon seçenekleri sayfasına girin, yerel cihaz bilgilerini güncellemek için `Seçenekler->Cihaz listesini güncelle`ye tıklayın.\n\nGeçerli ağ durumu: {network_status}\n{message}\n",
97+
"device_list_add": "\n**{count} yeni cihaz:** \n{message}",
98+
"device_list_del": "\n**{count} cihaz kullanılamıyor:** \n{message}",
99+
"device_list_offline": "\n**{count} cihaz çevrimdışı:** \n{message}",
100+
"network_status_online": "Çevrimiçi",
101+
"network_status_offline": "Çevrimdışı",
102+
"central_state_changed_title": "Merkezi Hub Ağ Geçidi Bağlantı Durumu",
103+
"central_state_changed": "**{nick_name}({uid}, {cloud_server})** Xiaomi merkezi hub ağ geçidine yerel bağlantı: {conn_status}",
104+
"central_state_connected": "Bağlandı",
105+
"central_state_disconnected": "Bağlantı kesildi",
106+
"device_exec_error": "Yürütme hatası"
107+
}
108+
},
109+
"error": {
110+
"common": {
111+
"-10000": "Bilinmeyen hata",
112+
"-10001": "Hizmet kullanılamıyor",
113+
"-10002": "Geçersiz parametre",
114+
"-10003": "Yetersiz kaynaklar",
115+
"-10004": "İç hata",
116+
"-10005": "Yetersiz izinler",
117+
"-10006": "Yürütme zaman aşımı",
118+
"-10007": "Cihaz çevrimdışı veya mevcut değil",
119+
"-10020": "Yetkisiz (OAuth2)",
120+
"-10030": "Geçersiz token (HTTP)",
121+
"-10040": "Geçersiz mesaj formatı",
122+
"-10050": "Geçersiz sertifika",
123+
"-704000000": "Bilinmeyen hata",
124+
"-704010000": "Yetkisiz (cihaz silinmiş olabilir)",
125+
"-704014006": "Cihaz açıklaması bulunamadı",
126+
"-704030013": "Özellik okunabilir değil",
127+
"-704030023": "Özellik yazılabilir değil",
128+
"-704030033": "Özellik abone edilebilir değil",
129+
"-704040002": "Hizmet mevcut değil",
130+
"-704040003": "Özellik mevcut değil",
131+
"-704040004": "Olay mevcut değil",
132+
"-704040005": "Eylem mevcut değil",
133+
"-704040999": "Özellik çevrimiçi değil",
134+
"-704042001": "Cihaz mevcut değil",
135+
"-704042011": "Cihaz çevrimdışı",
136+
"-704053036": "Cihaz işlemi zaman aşımı",
137+
"-704053100": "Cihaz mevcut durumda bu işlemi gerçekleştiremiyor",
138+
"-704083036": "Cihaz işlemi zaman aşımı",
139+
"-704090001": "Cihaz mevcut değil",
140+
"-704220008": "Geçersiz ID",
141+
"-704220025": "Eylem parametre sayısı uyumsuz",
142+
"-704220035": "Eylem parametre hatası",
143+
"-704220043": "Özellik değer hatası",
144+
"-704222034": "Eylem dönüş değer hatası",
145+
"-705004000": "Bilinmeyen hata",
146+
"-705004501": "Bilinmeyen hata",
147+
"-705201013": "Özellik okunabilir değil",
148+
"-705201015": "Eylem yürütme hatası",
149+
"-705201023": "Özellik yazılabilir değil",
150+
"-705201033": "Özellik abone edilebilir değil",
151+
"-706012000": "Bilinmeyen hata",
152+
"-706012013": "Özellik okunabilir değil",
153+
"-706012015": "Eylem yürütme hatası",
154+
"-706012023": "Özellik yazılabilir değil",
155+
"-706012033": "Özellik abone edilebilir değil",
156+
"-706012043": "Özellik değer hatası",
157+
"-706014006": "Cihaz açıklaması bulunamadı"
158+
}
159+
}
160+
}

0 commit comments

Comments
 (0)