Skip to content

Commit 06ddb55

Browse files
suraj-yadav0suraj-yadav0
committed
Merge remote-tracking branch 'origin/main'
2 parents d993358 + 0211daf commit 06ddb55

30 files changed

Lines changed: 1370 additions & 674 deletions

‎docs/contributing/app-translation-guide.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
title: App Translation and Localization Guide
3+
sidebar_label: App Translation
4+
description: A step-by-step guide for contributors to translate the Time Management App interface into different languages.
5+
---
6+
7+
# App Translation and Localization Guide
8+
9+
This guide provides step-by-step instructions for translating the **Time Management App** interface itself (the client application built with QML and Python) into your language.
10+
11+
The app's translation system is based on **gettext**. Translators edit `.po` (Portable Object) files containing key-value translation pairs, which are automatically compiled into binary `.mo`/`.gmo` files during the build process.
12+
13+
---
14+
15+
## 1. Directory Structure and Translation Files
16+
17+
All translation-related files are located in the `po/` directory at the root of the repository:
18+
19+
```text
20+
timemanagement/
21+
├── po/
22+
│ ├── CMakeLists.txt # Build system integration for translations
23+
│ ├── ubtms.pot # Portable Object Template (contains all untranslated strings)
24+
│ └── nl.po # Dutch translation source file (example of current translation)
25+
```
26+
27+
* **`ubtms.pot`**: The central template file extracted directly from the codebase. It contains all original English strings.
28+
* **`<locale_code>.po`**: Language-specific translation files (e.g., `nl.po` for Dutch, `es.po` for Spanish). This is the file you will create or modify.
29+
30+
---
31+
32+
## 2. Prerequisites
33+
34+
To contribute to translations, you should have the following tools installed:
35+
36+
1. **Gettext Utilities**: Command-line tools to initialize, merge, and compile translations.
37+
* **Ubuntu/Debian**:
38+
```bash
39+
sudo apt update && sudo apt install gettext
40+
```
41+
2. **Text Editor**: A standard text editor of your choice (such as VS Code, Vim, Gedit, etc.) to edit the translation files.
42+
3. **Clickable**: The build tool for the application, used to compile and test your translation locally. See the **Getting Started** guide for setup details.
43+
44+
---
45+
46+
## 3. Translation Workflow
47+
48+
### Step 1: Update the Translation Template (`ubtms.pot`)
49+
Before starting your translation, compile the project once to ensure the translation template `po/ubtms.pot` is updated with the latest strings from the source code:
50+
51+
```bash
52+
clickable build
53+
```
54+
*Note: The CMake build system automatically runs the translation extraction target, parsing all QML and desktop entry files to update `po/ubtms.pot`.*
55+
56+
### Step 2: Initialize or Update your Translation File
57+
58+
#### Option A: Starting a New Language
59+
Determine your 2-letter language code (and optional region, e.g., `fr` for French, `es` for Spanish, `pt_BR` for Brazilian Portuguese).
60+
Navigate to the `po/` directory and initialize the translation file using `msginit`:
61+
62+
```bash
63+
cd po
64+
msginit --locale=<locale_code> --input=ubtms.pot --output=<locale_code>.po
65+
```
66+
*Example for Spanish:*
67+
```bash
68+
msginit --locale=es --input=ubtms.pot --output=es.po
69+
```
70+
71+
#### Option B: Updating an Existing Language
72+
If you are translating new strings added to an existing translation (e.g., Dutch `nl.po`), merge the updated template into the translation file using `msgmerge`:
73+
74+
```bash
75+
cd po
76+
msgmerge --update <locale_code>.po ubtms.pot
77+
```
78+
*Example for Dutch:*
79+
```bash
80+
msgmerge --update nl.po ubtms.pot
81+
```
82+
This adds any new strings, marks deleted strings as obsolete, and flags altered strings as `#, fuzzy` for your review.
83+
84+
---
85+
86+
### Step 3: Translating the Strings
87+
Open your `<locale_code>.po` file in your text editor.
88+
89+
For each entry, translate the source string (`msgid`) to the translation string (`msgstr`):
90+
91+
```po
92+
msgid "Time Manager - Time Management Dashboard"
93+
msgstr "Tijdbeheer - Dashboard Tijdbeheer"
94+
```
95+
96+
#### Key Rules & Best Practices:
97+
1. **Preserve Placeholders**: Keep parameters like `%1`, `%2`, or `%3` intact. They represent dynamic values substituted at runtime.
98+
* *Example*: `i18n.dtr("ubtms", "You have %1 new notification(s)")` -> `Je hebt %1 nieuwe melding(en)`
99+
2. **Preserve Escape Sequences**: Characters like `\n` (newlines) or `\t` (tabs) must remain in the translated string.
100+
3. **Remove Fuzzy Flags**: If you update a string marked with `#, fuzzy`, remove the `# fuzzy` comment line after verifying the translation is correct. Otherwise, it won't compile.
101+
102+
---
103+
104+
### Step 4: Testing Your Translation Locally
105+
106+
1. Build the application with Clickable to compile the `.po` translation file to a binary `.mo` catalog:
107+
```bash
108+
clickable build
109+
```
110+
2. Run the desktop version of the application with your target language configured in the environment:
111+
```bash
112+
LANG=<locale_code>.UTF-8 clickable desktop
113+
```
114+
*Example for Dutch:*
115+
```bash
116+
LANG=nl_NL.UTF-8 clickable desktop
117+
```
118+
3. Verify that all translated elements show up correctly in the UI and that there are no layout or text clipping issues.
119+
120+
---
121+
122+
## 4. Code Guidelines for Developers (Marking Strings)
123+
124+
If you are writing code (QML) and want to ensure your text can be translated, use the following patterns:
125+
126+
### In QML / JavaScript
127+
* **Standard Translations**:
128+
```qml
129+
title: i18n.dtr("ubtms", "Settings")
130+
```
131+
* **Translating with Arguments**:
132+
```qml
133+
text: i18n.dtr("ubtms", "Account [%1]").arg(accountName)
134+
```
135+
* **Plural Forms**:
136+
Use `i18n.tr` with plural forms when displaying quantities:
137+
```qml
138+
// Syntax: i18n.tr(singular, plural, count)
139+
text: i18n.tr("You have %1 task", "You have %1 tasks", count).arg(count)
140+
```
141+
142+
### In Desktop Entries (`ubtms.desktop.in`)
143+
For system-level desktop configurations, prefix the translatable keys with an underscore:
144+
```desktop
145+
_Name=Time Management
146+
```
147+
*The build system uses `intltool` to extract these desktop keys into `ubtms.pot`.*
148+
149+
---
150+
151+
## 5. Submitting Your Contribution (Creating the PR)
152+
153+
Once you've tested your translations and verified that the `.po` file is correct, you are ready to submit a Pull Request (PR):
154+
155+
1. **Clean up backup files**: Some editors create temporary backup files (e.g., `nl.po~` or `nl.po.bak`). Delete these before committing.
156+
2. **Create a Git Branch**:
157+
```bash
158+
git checkout -b translation/add-<locale_code>
159+
```
160+
3. **Stage and Commit**:
161+
```bash
162+
git add po/<locale_code>.po
163+
git commit -m "translation: Add <Language_Name> translation"
164+
```
165+
4. **Push the Branch**:
166+
```bash
167+
git push origin translation/add-<locale_code>
168+
```
169+
5. **Open the Pull Request**:
170+
* Navigate to the original repository on GitHub.
171+
* Click **Compare & pull request**.
172+
* Fill out the PR template, ensuring you describe the language you added or updated, and confirm that you built and tested it locally.

‎docs/user/user-manual/NL-Translation.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: NL Translation
3+
sidebar_label: NL Translation
4+
description: Learn how to change your device's system language to Dutch (Nederlands) to view the application content in Dutch.
5+
---
6+
7+
# NL Translation (Dutch Language Support)
8+
9+
The application automatically adapts to your device's system language. If you want to view the app content in Dutch (Nederlands), you will need to update your phone's system settings.
10+
11+
---
12+
13+
## How to Change the App Language to Dutch
14+
15+
Follow these steps to change your display language:
16+
17+
1. Open your phone's **System Settings**.
18+
2. Search for or navigate to the **Language** or **Language and Text** options.
19+
3. Select **Display Language** and choose **Nederlands** (Dutch) from the list of available languages.
20+
4. If your device prompts you with a message to either restart or cancel, choose **Restart** to apply the changes.
21+
5. Once your phone successfully restarts, open the application. The content will now be displayed in Dutch.

‎docs/user/user-manual/about-us.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: About Us
3+
sidebar_label: About Us
4+
description: Discover the capabilities and purpose of the Time Management application. Find version details, benefits, and system information in our About Us section.
5+
---
6+
17
# About Us
28

39
The **About Us** section provides essential information about the Time Management application, including its purpose, version details, and key capabilities. It can be accessed from the **Main Navigation Menu**.

‎docs/user/user-manual/activities.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Activities
3+
sidebar_label: Activities
4+
description: A comprehensive guide to the Activities module. Find out how to access the dashboard, create and edit activities, filter by status, and manage your workflow efficiently.
5+
---
6+
17
# Activities
28

39
The **Activities** module is used to create, manage, track, and monitor daily activities within the Time Management App.

‎docs/user/user-manual/all-tasks.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: All Tasks
3+
sidebar_label: All Tasks
4+
description: A comprehensive guide to the Tasks module. Find out how to create and edit tasks, manage task stages, use swipe actions, and filter by assignees for efficient workload tracking.
5+
---
6+
17
# Tasks
28

39
The **Tasks** module helps users create, organize, assign, and track individual or all work items within the Time Management App.

‎docs/user/user-manual/dashboard.md‎

Lines changed: 51 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Dashboard
3+
sidebar_label: Dashboard
4+
description: An overview of the Time Management App Dashboard, featuring the Priority Matrix, time distribution charts, and quick navigation for projects and tasks.
5+
---
6+
17
# Dashboard
28

39
## Introduction
@@ -11,11 +17,11 @@ This screen enables users to:
1117
---
1218

1319
## Dashboard Overview
14-
The Dashboard consists of the following sections:
20+
The Dashboard consists of the following key sections:
1521
1. Header (Top Bar)
16-
2. Priority Matrix
17-
3. Charts
18-
4. Projects Section
22+
2. Unsaved Drafts Alert
23+
3. Priority Matrix
24+
4. Navigation Tabs (Overview, Projects, Tasks)
1925
5. Quick Action Button
2026

2127
---
@@ -24,66 +30,69 @@ The Dashboard consists of the following sections:
2430
Located at the top of the screen.
2531

2632
### Features:
27-
* **Account Name**: Displays the active user account.
28-
* **Menu Icon (☰)**: Opens the side navigation menu.
29-
* **Notification Icon (🔔)**: Displays alerts and updates.
30-
* **Add Icon (➕)**: Used to create a new timesheet entry.
31-
* **Kebab Menu Icon (⋮)**: Opens the overflow menu with additional navigation options.
33+
* **Menu Icon (☰):** Opens the side navigation menu.
34+
* **Account Name:** Displays the active user account.
35+
* **Add Icon (Clock with +):** Used to quickly create a new timesheet entry.
36+
* **Notification Icon (🔔):** Displays alerts and updates.
37+
* **Info Icon (ⓘ):** Provides additional information about dashboard chart guide.
3238

3339
---
3440

35-
## Priority Matrix
36-
The Priority Matrix categorizes tasks based on **urgency** and **importance**.
41+
## Unsaved Drafts Alert
42+
Upon launching the app, if there is unsubmitted work, an **Unsaved Drafts Found** popup may appear.
43+
* Notifies the user of unsubmitted work from a previous session (e.g., Timesheets, Project Updates).
44+
* Prompts the user to open the respective forms to restore their changes.
3745

38-
### Categories:
39-
**Do First (Urgent & Important)**
40-
* Tasks that require immediate attention.
41-
42-
**Do Next (Not Urgent & Important)**
43-
* Important tasks that can be scheduled.
46+
---
4447

45-
**Do Later (Urgent & Not Important)**
46-
* Tasks that can be postponed or delegated.
48+
## Priority Matrix
49+
The Priority Matrix categorizes tasks based on urgency and importance. It is organized visually with **URGENT** and **NOT URGENT** on the top axis, and **IMPORTANT** and **NOT IMPORTANT** on the side axis.
4750

48-
**Don’t Do (Not Urgent & Not Important)**
49-
* Tasks that are unnecessary.
51+
### Categories:
52+
* **Do First (Urgent & Important):** Tasks that require immediate attention (Red tile).
53+
* **Do Next (Not Urgent & Important):** Important tasks that can be scheduled (Blue tile).
54+
* **Do Later (Urgent & Not Important):** Tasks that can be postponed or delegated (Green tile).
55+
* **Don’t Do (Not Urgent & Not Important):** Tasks that are unnecessary (Grey tile).
5056

5157
### Time Display:
5258
Each category displays total time spent (e.g., `0H`), helping users evaluate productivity and time allocation.
5359

5460
---
5561

56-
## Charts
62+
## Navigation Tabs
63+
Below the Priority Matrix, the dashboard is divided into three primary tabs: **Overview**, **Projects**, and **Tasks**.
5764

58-
**Most Time-Consuming Projects (Donut Chart)**
59-
* Visual representation of time distribution across projects.
60-
* Larger segments indicate higher time usage.
65+
### 1. Overview Tab
66+
Displays visual charts for time tracking.
67+
* **Most Time-Consuming Projects (Donut Chart):** Visual representation of time distribution across projects. Larger segments indicate higher time usage.
68+
* **Project-wise Time Spent (Bar Chart):** Displays time spent per project. The axes allow visual comparison of effort across projects. Includes a **"Show next 10 ↓"** button at the bottom to load more data.
6169

62-
**Project-wise Time Spent (Bar Chart)**
63-
* Displays time spent per project.
64-
* X-axis: Project names.
65-
* Y-axis: Time (in hours).
66-
* Bars allow visual comparison of effort across projects.
70+
### 2. Projects Tab
71+
Displays detailed information about user projects, along with a master total of hours logged across all projects.
6772

68-
---
6973

70-
## Projects Section
71-
Displays detailed information about user projects.
74+
### 3. Tasks Tab
75+
A dedicated tab for managing and viewing individual tasks.* **"Show next 10" and "Show fewer"** buttons are available at the bottom to expand the projects list.
7276

73-
### Features:
74-
* **Total Time Spent** (e.g., `0.0 h`).
75-
* **Progress Indicator**: Visual bar showing time utilization.
76-
* **Search Bar ("Search projects…")**: Enables quick project lookup.
7777

78-
### Sorting and Filtering Options:
79-
* **Most Time**: Sort by highest time spent.
80-
* **Tasks**: Sort by number of tasks.
81-
* **A–Z**: Alphabetical sorting.
78+
* **Search Bar:** Enables quick project lookup ("Search projects…").
79+
* **Sorting Options:**
80+
* **Most Time:** Sort by highest time spent.
81+
* **Tasks:** Sort by number of tasks.
82+
* **A–Z:** Alphabetical sorting.
83+
* **Project List:** Displays individual projects with their specific task counts, total time spent, and a visual progress indicator.
84+
85+
**Project Details View:**
86+
Tapping on a specific project in the list navigates to a detailed view for that project, which includes:
87+
* A summary header displaying the `TOTAL` time, `AVERAGE` time, total `TASKS`, and the `TOP TASK`.
88+
* A specific bar chart breaking down time spent by individual tasks within that project.
89+
* A list of individual tasks showing their percentage of project time, total hours, and a navigation arrow for further details.
90+
8291

8392
---
8493

8594
## Quick Action Button
86-
A floating action button located at the bottom-right corner.
95+
A floating action button (cyan circle with a menu icon) located at the bottom-right corner of the screen.
8796

8897
### Functions:
8998
* Add a new task.

0 commit comments

Comments
 (0)