InstrumentKit

InstrumentKit 提供对本地化乐器及其调音的类型安全访问。

• 开发中
• 安装
• 使用
• 性能
• 贡献
• 鸣谢
• 许可证

⚠️这个包仍在积极开发中。以下是一些后续步骤。

• 目前，这个包主要关注收集、验证和本地化仅限弦乐器的数据。 一旦弦乐器的数据准确、稳定且经过了充分的测试，计划将添加铜管乐器、键盘乐器、打击乐器等。
• 该库目前利用一个内部依赖项进行音乐符号表示 (NoteKit)，但应尽快替换为更准确且维护更好的 AudioKit/Tonic。 音乐数学和理论非常复杂，而 InstrumentKit 不想涉足音乐数学或理论。
• 提供一种机制，确保部分本地化模型默认提供英语值。 目前，它们会回退到 localizationKey，这意味着将 "Guitar" 翻译成一个没有 "guitar" 键的部分本地化，会显示为 "guitar"，而不是 "Guitar"。
  • 这对于缺失的本地化已经有效，但不适用于部分本地化。
  • 实现此功能应该不需要花费太多精力，也不会降低性能。

Swift Package Manager 内置于 Swift 工具链中，是集成 SDK 的首选方法。

除了与 Apple 平台（iOS、macOS、tvOS、watchOS）兼容之外，该软件包还与 Linux 完全兼容，使其非常适合 服务器端 Swift 项目。

对于 Swift package 项目，只需将以下行添加到 Package.swift 文件的 dependencies 部分，并将 x.x.x 替换为最新版本

dependencies: [
  .package(url: "https://github.com/bdrelling/InstrumentKit", .from: "x.x.x"),
]

对于应用程序项目，只需按照 Apple 文档 将 package 依赖项添加到您的应用程序中。

struct StringInstrument {
    let localizationKey: String
    let name: String
    let numberOfStrings: Int
    let numberOfCourses: Int
    let tunings: [Tuning]
}

struct Tuning {
    let localizationKey: String
    let name: String
    let notes: [Note]
}

获取特定的弦乐器。

let guitar: StringInstrument = .guitar
let ukulele: StringInstrument = .ukulele
let irishBouzouki: StringInstrument = .irishBouzouki

获取所有弦乐器。

let instruments: [StringInstrument] = StringInstrument.allCases
let instruments: [StringInstrument] = .allCases

集合提供了一个 .allCases 便利扩展，因此您不必每次都写出元素的名称。

获取乐器的特定调音。

let guitarStandard: Tuning = Tuning.Guitar.standard.rawValue

获取乐器的所有调音。

let guitarTunings: [Tuning] = StringInstrument.guitar.tunings
let guitarTunings: [Tuning] = Tuning.Guitar.allTunings

allTunings 作为 allCases.map(\.rawValue) 的便利方法提供。

默认情况下，每个 StringInstrument 和 Tuning 都会被本地化到 Locale.current。 但是，您也可以通过使用 Locale、区域设置标识符 (String) 或使用 SupportedLanguage enum 调用 .localized(to:)，动态地本地化模型。

本地化一个模型。

let guitarra: StringInstrument = .guitar.localized(to: "es")
let estandard: Tuning = Tuning.Guitar.standard.localized(to: "es")

本地化一个集合的模型。

let spanishInstruments: [StringInstrument] = .allCases.localized(to: "es")
let spanishGuitarTunings: [Tuning] = Tuning.Guitar.allTunings.localized(to: "es")

正在寻找本地化的乐器和调音定义，但不使用 Swift？ 没问题！

此包中的所有乐器和调音也可以通过向 instruments.fyi 发出 API 请求来获得。 您可以获取所有乐器、特定乐器、调音等。

有关更多信息，请参阅 instruments.fyi 或访问 instruments.fyi。

此模块中 String 本地化的使用与 Bundle.localizedString(forKey:value:table:) 和 NSLocalizedString 的标准使用相匹配。 通过每次都通过本地化表初始化这些字符串，确保任何使用该模块的人都可以直接获得本地化，而无需任何额外的工作，因为他们将始终使用 Locale.current 进行本地化。

在 Tuning+Definitions.swift 中看到以下内容可能会让您感到不舒服

enum Guitar: Tuning, CaseIterable {
    case standard = "standard: E2 A2 D3 G3 B3 E4"
    case dropD = "drop_d: D2 A2 D3 G3 B3 E4"
    case openD = "open_d: D2 A2 D3 F#3 A3 D4"
}

采取这种方法并非轻率之举。 乐器有数十种常用的调音，而且有数百种乐器。 如果没有一种易于解析的方法来分析、比较和事实核查数据，那么维护一个大型数据集会变得非常困难。

String 对 Tuning 的解析发生在 Tuning+Definitions.swift 底部的特殊 init 中。 通过使 Tuning 符合 ExpressibleByStringLiteral，它允许我们创建易于验证的 CaseIterable 枚举，并且可以开箱即用地提供 Tuning 集合和组织功能。

逻辑很简单，并且非常容易验证：循环遍历项目中的每个 Tuning，如果我们的任何受支持语言中的任何本地化键返回任何类型的错误，项目中的许多单元测试将会崩溃。

此外，这些枚举只初始化一次，这意味着如果您一直重复访问这些枚举中的一个，您可以确定它不会每次都重新解析 Tuning 定义。

如果您有其他建议，请随时提出问题或提出 pull request。 在最终确定 String 初始化的 Tuning 之前，已经考虑了几种方法，但新鲜的视角总是有帮助的。 如果您有一种性能良好的方式来定义这些数据，该方式是类型安全的，但提供相同级别的便利性和可读性（用于维护和数据准确性），我很感兴趣！

非常欢迎进行讨论、提出问题和提出 pull request，用于开发、更正和/或本地化。

如果您提供更正和/或本地化，请尽可能提供更多其他来源进行验证，以帮助确保我们可以尽快集成更正。

特别感谢 AudioKit 的所有专业知识和支持。

本项目根据 MIT 许可证发布。 有关详细信息，请参阅 LICENSE。