iTopCN – 定制化 iTop

Docs: 翻译

Sun, 03 Sep 2023 00:00:00 +0000

本文档介绍 iTop 的翻译机制，包括字典文件格式、命名约定以及如何为现有语言贡献翻译。更多详细内容请参考 iTop 官方文档。

原则

在 iTop 和 iTop 模块中，语言由两个要素确定：

ISO 639-1 语言代码。例如：pt 表示葡萄牙语。
ISO 国家代码。例如：br 表示巴西。

本地化依赖于字典文件，这些文件的名称以小写语言代码作为前缀，例如：pt_br.dictionary.itop.core.php。这些文件是数据模型的一部分，因此在每次修改后都需要进行编译（重新运行安装或使用工具包）。

在 iTop 中，嵌入的字典文件位于以下位置：

<itop-root>/dictionaries/
<itop-root>/datamodels/2.x/<module>/dictionaries

在模块中，这些文件位于模块的根目录。

自 iTop 3.0.0（N°2969）起，模块的字典文件可以位于模块的根文件夹或名为 dictionaries 的子文件夹中。

出于兼容性原因，作为扩展分发的模块保留了它们的字典文件在根文件夹中的方式，但 iTop 核心模块（datamodels/2.x）已经进行了修改。

字典文件格式

字典实际上是一个 PHP 文件。它必须以 UTF-8 字符集编码（这是必须的）。我们建议像下面的示例一样省略 PHP 的结束标记：

<?php
/**
 * Localized data
 *
 * @copyright Copyright (C) 2015 John Foo Ltd
 * @author John Foo (john@foo.com)
 * @license http://opensource.org/licenses/AGPL-3.0
 */

Dict::Add('PT BR', 'Brazilian', 'Portuguese', array(
 'Menu:ChangeManagement' => 'Gerenciamento Mudanças',
 'Menu:Change:Overview' => 'Visão geral',
 'Menu:NewChange' => 'New Change~~',
));

注意事项：

函数调用的第一个参数是大写的语言代码。
函数调用的第二个参数是英语中的语言名称。
函数调用的第三个参数是目标语言中的语言名称。
Dict::Add 函数的行在所有相同语言的字典文件中必须相同（是的，这里有冗余信息）。
请注意某些字符串末尾的 ~~。这个后缀不会显示给最终用户。它由 Combodo 在发布新版本时添加，用于显示哪些新字符串需要翻译。

一些通用规则

保持一致性： 重复使用已经翻译的术语（例如，“经理"是许多关键词中使用的词汇）。
英文术语： 如果在上下文中更容易理解，可以保留英文术语。
避免过于口语化的表述： iTop 是一款既被公司使用又被其客户使用的产品。
不要硬编码 “iTop” 名称： 使用常量（它们在 core/config.class.inc.php 中定义）：
- ITOP_APPLICATION：应用程序包的完整名称，例如 “iTop Community” 或 “iTop Professional”。
- ITOP_APPLICATION_SHORT：应用程序的名称，例如 “iTop”。
类名命名方式： 使用驼峰命名法。
数据模型项目命名标准： Class:<classname>、Class:<classname>/Attribute:<fieldname>。例如：Class:Ticket、Class:Ticket/Attribute:ref、Class:UserRequest/Attribute:status/Value:new。
字段标签翻译： 请在定义字段的类中进行翻译，而不是在子类中进行。例如，对于 Class:Ticket/Attribute:ref 是可以的，但对于 Class:Change/Attribute:ref 则不应该。如果需要后者，可以使用自定义模块将其添加到您的 iTop 实例中。
操作标签中的类别： 尽量不要在通用用户的操作标签中提及类别。但对于管理员用户可以这样做。如果使用类别标签，请将其大写化，例如将 “notification” 改为 “Notification”。
特殊条目 Class:<classname>/Attribute:friendlyname： 在英文中显示为 “Full name”，如果没有翻译，它不对应于特定的类字段，而是对应于用作外部键、对象列表和对象详情中的对象标签的魔法属性。

这些规则有助于维护和确保翻译的一致性。

键语法	用途	示例
`Class:<classname>`	翻译类的名称	`Class:Ticket`
`Class:<classname>/Attribute:<fieldname>`	翻译字段标签	`Class:Ticket/Attribute:ref`
`Class:<classname>/Attribute:<fieldname>/Value:<value>`	翻译枚举属性的值	`Class:UserRequest/Attribute:status/Value:new`
`Class:<classname>/Attribute`	格式化友好名称值（参见下方示例）	`'Class:Person/Name' => '%2$s %1$s'`

Friendlyname 语法

在这个示例中：

'Class:Person/Name' => '%2$s, %1$s', /* 示例："Christie, Agatha" */

%1$s 对应于 Person 类的命名 XML 标签中的第一个字段，因此是 first_name。
%2$s 对应于 Person 类的命名 XML 标签中的第二个字段，因此是 name。

这允许指定不同的顺序，甚至一些其他字符和分隔符。

<classes>
 <class id="Person">
 <properties>
 <naming>
 <attributes>
 <attribute id="first_name"/> <!-- 映射到 %1$s -->
 <attribute id="name"/> <!-- 映射到 %2$s -->
 </attributes>
 </naming>

字典关键词的命名约定

新条目的命名应根据其领域和目的，从最不具体的信息开始命名。

最常用的分隔符是 :，但也可以找到 / 和 -。

'Core:BulkExport:TextFormat' => 'Text fields containing some HTML markup',
'UI:CSVImport:TextQualifierCharacter' => 'Text qualifier character',
'DayOfWeek-Sunday-Min' => 'Su',

使用后缀来定义相同标签的变种：

+ 表示短描述（通常显示在工具提示中）
? 表示帮助/解释（可以跨多行）

'Core:SynchroAtt:update' => 'Update ?',
'Core:SynchroAtt:update+' => 'Used to update the object',

'UI:CSVImport:AdvancedMode' => 'Advanced mode',
'UI:CSVImport:AdvancedMode+' =>
 'In advanced mode the "id" (primary key) of the objects can be used to update and rename objects.'
 .'However the column "id" (if present) can only be used as a search criteria'
 .' and can not be combined with any other search criteria.',

当建立了命名约定后，标识符应该指定为 <name>:<value>，就像以下示例中的方式：

'Class:Event/Attribute:date' => 'Date',
'Class:Event/Attribute:date+' => 'date and time at which the changes have been recorded',

请注意，在这种情况下，分隔符应该是 /。

枚举值

枚举或枚举集的值使用自己的语法：

'Class:Action/Attribute:status/Value:test' => 'Being tested',
'Class:Action/Attribute:status/Value:test+' => 'Action has maybe a different behavior than when in production',
'Class:Action/Attribute:status/Value:enabled' => 'In production',
'Class:Action/Attribute:status/Value:enabled+' => '',
'Class:Action/Attribute:status/Value:disabled' => 'Inactive',
'Class:Action/Attribute:status/Value:disabled+' => 'Action is not effective',

实体覆盖

子类可以覆盖属性（或值）的标签/工具提示，即使该属性已在其父类之一中定义。

'Class:ActionEmail/Attribute:status/Value:test+' => 'Only the Test recipient is notified',
'Class:ActionEmail/Attribute:status/Value:enabled+' => 'All To, Cc and Bcc emails are notified',
'Class:ActionEmail/Attribute:status/Value:disabled+' => 'The email notification will not be sent',
'Class:ActionEmail/Attribute:test_recipient' => 'Test recipient',

关系

默认链接相关的操作/图标工具提示、弹出窗口标题和确认消息如下所示。

它们可以根据需要进行自定义，甚至可以根据类别/关联设置属性进行定制化（请参阅下文）。

1:n 关系

通用字典条目代码	用途	英文	法文
`UI:Links:Create:Button+`	列表右上角的加号图标工具提示	Create a %4$s	Créer un(e) %4$s
`UI:Links:Create:Modal:Title`	子对象创建弹出窗口标题	Create a %4$s in %2$s	Ajouter un(e) %4$s à %2$s
`UI:Links:ModifyObject:Button+`	行右端的铅笔图标工具提示	Modify this object	Modifier cet objet
`UI:Links:ModifyObject:Modal:Title`	子对象修改弹出窗口标题	Modify %5$s	Modifier %5$s
`UI:Links:Remove:Button+`	行右端的减号图标工具提示	Remove this %4$s	Retirer cet(te) %4$s
`UI:Links:Remove:Modal:Title`	子对象从其宿主中移除弹出窗口标题	Remove a %4$s from its %1$s	Retirer un(e) %4$s de son/sa %1$s
`UI:Links:Remove:Modal:Message`	子对象移除的确认消息	Do you really want to remove %5$s from %2$s?	Voulez vous vraiment retirer %5$s de %2$s ?
`UI:Links:Delete:Button+`	行右端的垃圾桶图标工具提示	Delete this %4$s	Supprimer cet(te) %4$s
`UI:Links:Delete:Modal:Title`	子对象删除弹出窗口标题	Delete a %4$s	Supprimer un(e) %4$s
`UI:Links:Delete:Modal:Message`	子对象删除的确认消息	Do you really want to delete %5$s?	Voulez vous vraiment supprimer %5$s ?

n:n 关系

通用字典条目代码	用途	英文	法文
`UI:Links:Add:Button+`	列表右上角的加号图标工具提示	Add a %4$s	Ajouter un %4$s
`UI:Links:Add:Modal:Title`	链接创建弹出窗口标题	Add a %4$s to %2$s	Ajouter un %4$s à %2$s
`UI:Links:ModifyLink:Button+`	行右端的铅笔图标工具提示	Modify this link	Modifier cette relation
`UI:Links:ModifyLink:Modal:Title`	链接修改弹出窗口标题	Modify the link between %2$s and %5$s	Modifier la relation entre %2$s et %5$s
`UI:Links:Remove:Button+`	行右端的减号图标工具提示	Remove this %4$s	Retirer ce %4$s
`UI:Links:Remove:Modal:Title`	链接删除弹出窗口标题	Remove a %4$s	Retirer un %4$s
`UI:Links:Remove:Modal:Message`	链接删除的确认消息	Do you really want to remove %5$s from %2$s?	Voulez vous vraiment retirer %5$s de %2$s ?

占位符

$%1s：宿主对象类名称（本地化）
$%2s：宿主对象友好名称
$%3s：宿主对象内的当前标签名称（本地化）
$%4s：远程对象类名称（本地化）
$%5s：远程对象友好名称（注意：并非所有情况下都可用，需要检查！）

专用化

除非为给定类的特定 LinkedSet（或 LinkedSetIndirect）属性定义了更具体的条目，否则使用上面的通用条目代码。

以下是考虑法语中类别属性的覆盖逻辑示例：

Dict::Add('FR FR', 'French', 'Français', array(
 'Class:Person/Attribute:team_list/UI:Links:Add:Button+' => 'Ajouter une %4$s',
 'Class:Person/Attribute:team_list/UI:Links:Add:Modal:Title' => 'Ajouter une %4$s à %2$s',
 'Class:Person/Attribute:team_list/UI:Links:Remove:Button+' => 'Retirer cette %4$s',
 'Class:Person/Attribute:team_list/UI:Links:Remove:Modal:Title' => 'Retirer une %4$s',
 'Class:Team/Attribute:persons_list/UI:Links:Add:Button+' => 'Ajouter une %4$s',
 'Class:Team/Attribute:persons_list/UI:Links:Add:Modal:Title' => 'Ajouter une %4$s à %2$s',
 'Class:Team/Attribute:persons_list/UI:Links:Remove:Button+' => 'Retirer cette %4$s',
 'Class:Team/Attribute:persons_list/UI:Links:Remove:Modal:Title' => 'Retirer une %4$s'
));

最终用户门户

如果您添加了一个新的终端用户门户，您可能希望创建一个字典条目，以便为其创建一个真实的标签。要做到这一点，请按照以下语法进行操作：

// 默认门户
'portal:itop-portal' => 'Standard portal',
'portal:<YOUR_PORTAIL_ID>' => 'Your new portal label',

UI 主题

如果您为后台创建了一个新主题，您可能希望创建一个字典条目，以便用户在首选项页面中选择它时能够获得一个漂亮的标签。要做到这一点，请按照以下语法进行操作：

// 默认主题
'theme:fullmoon' => 'Full Moon 🌕',
'theme:<YOUR_THEME_ID>' => 'Your new theme label',

如何贡献改进现有语言

要改进现有语言，您需要执行以下步骤：

从 iTop 主存储库或相关的模块存储库创建一个分支（Fork）。
在您的分支上进行修改，并按需改进现有语言的翻译。
提交拉取请求（Pull Request）：有关详细的提交步骤，请查看您正在修改的存储库中的 CONTRIBUTING.md 文件。GitHub 的帮助页面也提供了关于从分支创建拉取请求的详细信息。

为现有语言添加翻译：使用 grep 命令查找包含 ~~ 的文本，并在原地进行翻译。

以下是在 Linux 命令行中查找包含 ~~ 标记的德语（de）字典条目的快速命令：
find -name "de*dict*.php" | grep -v "env-" | xargs grep "~~"
要查找其他语言的字典条目，只需将命令中的 de* 更改为您想处理的语言代码（例如 fr、it、sp 等），然后从安装 iTop 的目录运行此命令。这将帮助您找到包含 ~~ 标记的文本行，以便进行翻译。

为新语言添加翻译：首先找到您的语言代码和国家代码。然后将英语文件（dictionary.*.php 或 en.dict.*.php）复制到相应的目录中，并使用相关的前缀（例如，pt_br.dict…）。然后对这些文件进行翻译。

不要忘记修改 Dict::Add 函数调用的参数。如果不这样做，将在运行时用您的翻译覆盖英语文本。

提交的拉取请求将由 Combodo 的维护人员进行分析，并最终合并到原始存储库中。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:translation

版本：3_2_0/customization/translation.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: How to 示例

Fri, 27 Jun 2025 00:00:00 +0000

{% pageinfo %} 本文档介绍 How to 示例。更多详细内容请参考 iTop 官方文档。 {% /pageinfo %}

概述

How to 示例是 iTop 定制中的常见场景。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:start#how_to_examples

Last modified: 2026/06/10 17:31 by127.0.0.1

版本：3_2_0/customization/start.txt · Last modified: 2026/06/10 17:31 by 127.0.0.1

Docs: 编写自己的扩展

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 定制的整体概览，包括通过安装现有扩展和编写自定义扩展两种方式。更多详细内容请参考 iTop 官方文档。

定制方式

安装现有扩展

查看已发布的扩展列表，选择并安装适合您需求的扩展。

编写自己的扩展

创建 iTop 扩展模块的基础知识：

了解 iTop 定制机制，理解如何扩展或修改 iTop。
参考逐步示例，创建您的第一个扩展。
使用扩展骨架生成工具创建新扩展，并了解文件结构。
使用对象操作 API 搜索和操作对象。
使用 CRUD 事件在对象上添加业务逻辑，事件遵循 CRUD 序列。
使用 Events API 添加自定义事件（iTop 3.1 新增）。
使用 Interfaces API 定制 GUI。
XML 数据模型参考和 XML Portal 参考。
iTop 编码标准。
图标使用 FontAwesome v5。

“How to” 示例

修改数据模型

类、字段与关系

属性用法与约束
为 Server 类添加字段
（重新）定义字典条目
强制字段始终必填
从 Ticket 中移除字段
为 Team 添加仪表板
创建新的 CI 类：Monitor
定义依赖关系
添加 1:1 关系
n-n 自反与对称关系
对象创建者
合并状态
在 PHP 中添加 TagSet
在 PHP 中添加日志条目
添加 n:n 关系
机密属性

生命周期：状态、转换、计时器

添加状态和转换
统计在状态中花费的时间
在状态延迟后通知
计时器行为
为物理设备添加生命周期
通过生命周期强制字段必填
在转换上执行操作
转换上可用的预定义方法
允许在非默认状态直接创建
在日志更新时重新分配工单
隐藏转换

认证与权限

创建新角色
委派"管理工具"菜单
定义密码策略
实现密码过期
创建自定义认证方式
防止用户意外被禁用

用户界面

必填、隐藏、控制

强制字段必填
将字段设为只读
为某些用户隐藏成本
表单预填充：创建表单预填充、转换预填充、搜索条件预填充
数据完整性检查：确保结束日期在起始日期之后、物理设备在生产环境时必须填写位置、防止 LinkedSet 变更超出库存、防止人员组织变更破坏门户用户关联、限制用户只能修改不能创建对象
定义过时规则
防止重复

显示

更改 iTop 主页
在"其他操作"弹出菜单中添加条目
为控制台仪表板创建新 dashlet：iFrame
丰富对象显示
区分同名对象
更改页面标题
对象间导航
隐藏对象标签页：影响分析或仪表板
在列表上添加操作
隐藏对象历史记录
添加对象概览
枚举值排序
转换排序
计算对象图标

主题与颜色

更改 iTop 徽标
更改颜色等
高亮关键对象
高亮状态
更改菜单图标
类颜色与图标
更改左侧菜单颜色
更改主色调
创建新主题

自动化

使用对象复制器复制 linkedset
计算工单结束日期
统计工单重新打开次数
在 1:n 上计算字段
在 n:n 上计算字段
存储 n:n 关系计数
从外部应用同步数据
将工单转移到另一个 iTop
存储 1:n 关系计数
在添加附件时添加日志条目
计算 linkedset 依赖值

工单管理

统计等待第三方的时间
考虑覆盖窗口计算解决延迟
统计用户请求重新打开次数
在延迟后自动关闭
计划日期开始的用户请求 TTO
计划用户请求（高级）
按服务子类别设置 SLA
从父组织继承服务
按国家使用节假日日历计算 SLA
级联变更关闭：在相关变更关闭时自动解决所有关联用户请求
使用中间商的服务提供商
在日志更新时重新分配工单

定制门户

自 2.3 版本起，增强型门户提供了定制选项。

门户定制概览
门户 XML 参考
门户限制

操作示例

在用户门户上强制字段必填
允许查看更多或更少的工单
为他人创建工单
更改范围
更改 Bootstrap 主题
更改菜单图标
添加"创建"按钮
添加新的浏览模式
添加 Dashlet
创建新门户
门户上的可选关系
为各种客户创建工单
在表单中定位附件

贡献 iTop 翻译

如何翻译

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:start

Last modified: 2026/06/10 17:31 by127.0.0.1

版本：3_2_0/customization/start.txt · Last modified: 2026/06/10 17:31 by 127.0.0.1