Better support for use in open source libraries

[liamnichols]

Currently, we direct you to use XCStrings Tool as a Build Tool plugin, which requires the plugin to be invoked whenever the target is compiled (if the catalog is modified).

This is great for direct use in your own projects as it keeps the generated source up-to-date automatically however it became clear that this is a bit problematic when used internally in an open source library that is offered to other developers because it requires them to trust the plugin before it runs yet the plugin itself is an implementation detail and that might confuse the developer who is adopting the open source library.

To overcome this, we can offer ways to generate the source code on-demand so that it can be bundled in the library release instead of being generated at compile time.

This can be made possible in two ways:

1. Document the CLI so that it can be invoked manually
2. Add a Command Plugin that replicates the Build Tool plugin by detecting the Strings Catalogs automatically

The first approach is just a case of adding documentation, but the second is a much friendlier user experience

[HarshilShah]

+1 for this as an app dev too, I think it'd be useful to check in the generated Swift code so it's easier to diff things when something changes

[joshuatbrown]

I'd love to have documentation for the CLI since it seems like Xcode 15.3 can't handle Build Tool plugins for SwiftUI Previews. Our Previews builds fail unless we build our targets manually first -- and it seems like this is true for both XCStringsTool and SwiftGen. If either is used as a Build Tool plugin, the Previews fail to build.

[liamnichols]

Thanks for raising this @joshuatbrown. I'm still using Xcode 15.2 and was not aware of this. That's a shame 😕

Do you happen to know if it's fixed in Xcode 15.4 or 16? I'll try and update my demo repo to see if I can reproduce and write a feedback if necessary.

As for CLI usage, I'll prioritise docs and a command plugin next 👍 In the meantime, I can share some info on how to use the executable directly if it helps.. It's quite straightforward:

swift run xcstrings-tool generate /path/to/Localizable.xcstrings --output /path/to/Localizable.swift

You invoke generate once per strings table, so if you have multiple Strings Catalogs, you need to invoke the executable multiple times.

If you're setting up as an Xcode run script build phase, you can set the input and output files. The only disappointing thing is that you can't dynamically discover the inputs like the build tool plugin can.

I don't distribute the executable via Homebrew or anything like that, but you can either download it from the Releases page, or use something like Mint or Mise if you weren't already familiar

[joshuatbrown]

@liamnichols I may be wrong; we're still trying to track down exactly why our SwiftUI Previews don't work as expected. It seems like it's because of build tool plugins, since Xcode shows compile errors that indicate it can't find the files that are generated by XCStringsTool. It also showed these for SwiftGen when we were using the SwiftGen Build Tool plugin, but I've switched over to the command-line invocation of SwiftGen and that seems to make Xcode happier in the Build for Previews. This is all in Xcode 15.3 -- we can't build on Xcode 15.4 or 16.0b1 due to this issue.

Thanks for the info on how to use the CLI! I'll try this out and see if it works for us!

[liamnichols]

Ah yes, Xcode often doesn't like files hidden away over in DerivedSources and throws up errors despite it not being an issue. Do let me know how you get on though 🙏

[joshuatbrown]

@liamnichols we decided to downgrade from Xcode 15.3 to 15.2. SwiftUI Previews work as expected in 15.2, so it seems like more recent versions of Xcode just have Previews bugs when using build tool plugins. This includes Xcode 16 beta 2 which I tested this morning. Here are the results of my testing in case you're interested. Thanks for all your help and support on this!